@matware/e2e-runner 1.2.1 → 1.3.1

package/src/mcp-tools.js

@@ -13,19 +13,50 @@ import path from 'path';
 import http from 'http';
 
 import { loadConfig } from './config.js';
-import { waitForPool, getPoolStatus, connectToPool } from './pool.js';
-import { runTestsParallel, loadTestFile, loadTestSuite, loadAllSuites, listSuites } from './runner.js';
+import { connectToPool } from './pool.js';
+import { waitForAnyPool, getPoolUrls, getAggregatedPoolStatus, selectPool } from './pool-manager.js';
+import { runTestsParallel, loadTestFile, loadTestSuite, loadAllSuites, listSuites, fetchAuthToken } from './runner.js';
 import { generateReport, saveReport, persistRun } from './reporter.js';
 import { narrateTest } from './narrate.js';
 import { startDashboard, stopDashboard } from './dashboard.js';
-import { lookupScreenshotHash, ensureProject, computeScreenshotHash, registerScreenshotHash, getNetworkLogs } from './db.js';
+import { lookupScreenshotHash, ensureProject, computeScreenshotHash, registerScreenshotHash, getNetworkLogs, setVariable, getVariables, deleteVariable, listVariables } from './db.js';
 import { fetchIssue, checkCliAuth, detectProvider } from './issues.js';
-import { buildPrompt, hasApiKey } from './ai-generate.js';
+import { buildPrompt, hasApiKey, generateHindsightHint } from './ai-generate.js';
 import { verifyIssue } from './verify.js';
 import { listModules } from './module-resolver.js';
-import { getLearningsSummary, getFlakySummary, getSelectorStability, getPageHealth, getApiHealth, getErrorPatterns, getTestTrends, getRunInsights, getTestHistory, getPageHistory, getSelectorHistory } from './learner-sqlite.js';
+import { getLearningsSummary, getFlakySummary, getSelectorStability, getPageHealth, getApiHealth, getErrorPatterns, getTestTrends, getRunInsights, getTestHistory, getPageHistory, getSelectorHistory, getHealthSnapshot, getTestCreationContext, generateImprovements, getActionHealthScores } from './learner-sqlite.js';
 import { queryGraph } from './learner-neo4j.js';
 import { startNeo4j, stopNeo4j, getNeo4jStatus } from './neo4j-pool.js';
+import { getAppPoolStatus, isAppPoolEnabled } from './app-pool.js';
+
+/**
+ * Resolves auth token from config: uses static authToken if set,
+ * otherwise auto-logs in via authLoginEndpoint + authCredentials.
+ * If the endpoint is a Docker-internal hostname (e.g. "nginx", "api")
+ * and fails with ENOTFOUND, retries with localhost.
+ * Returns the token string or null if no auth is configured.
+ */
+async function resolveAuthToken(config) {
+  if (config.authToken) return config.authToken;
+  if (config.authLoginEndpoint && config.authCredentials) {
+    const tokenPath = config.authTokenPath || 'token';
+    try {
+      return await fetchAuthToken(config.authLoginEndpoint, config.authCredentials, tokenPath);
+    } catch (err) {
+      // Docker-internal hostname? Retry with localhost from host machine
+      if (err.message && err.message.includes('ENOTFOUND')) {
+        const url = new URL(config.authLoginEndpoint);
+        if (!url.hostname.includes('.')) {
+          // Simple hostname (nginx, api, etc.) → likely Docker service name
+          const localhostUrl = `http://localhost${url.port && url.port !== '80' ? ':' + url.port : ''}${url.pathname}${url.search}`;
+          return await fetchAuthToken(localhostUrl, config.authCredentials, tokenPath);
+        }
+      }
+      throw err;
+    }
+  }
+  return null;
+}
 
 // ── Tool definitions ──────────────────────────────────────────────────────────
 
@@ -65,6 +96,11 @@ export const TOOLS = [
           type: 'boolean',
           description: 'Fail tests when network requests fail (e.g. ERR_CONNECTION_REFUSED). Default: false.',
         },
+        verificationStrictness: {
+          type: 'string',
+          enum: ['strict', 'moderate', 'lenient'],
+          description: 'Visual verification strictness. strict: no ambiguity allowed, any doubt = FAIL. moderate: reasonable judgment (default). lenient: only fail on clear contradictions.',
+        },
         cwd: {
           type: 'string',
           description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
@@ -89,35 +125,94 @@ export const TOOLS = [
   {
     name: 'e2e_create_test',
     description:
-      'Create a new E2E test JSON file. Provide the suite name and an array of test objects, each with a name and actions array. Actions can include { "$use": "module-name", "params": {...} } to reference reusable modules.',
+      `Create a new E2E test JSON file. IMPORTANT: prefer built-in actions over evaluate blocks.
+
+## Action selection guide (use instead of evaluate)
+
+**Clicking elements by text** — DON'T write evaluate to find+click elements:
+  click:           { type: "click", text: "Submit" }              — searches button, a, [role=tab], span, etc.
+  click_regex:     { type: "click_regex", text: "save|guardar" }  — regex match, case-insensitive
+  click_menu_item: { type: "click_menu_item", text: "Delete" }    — [role=menuitem], .MenuItem, etc.
+  click_option:    { type: "click_option", text: "Option A" }     — [role=option] in dropdowns
+  click_chip:      { type: "click_chip", text: "Active" }         — MUI Chip / tag elements
+  click_icon:      { type: "click_icon", value: "edit" }          — SVG/icon by data-testid, aria-label, class
+  click_in_context:{ type: "click_in_context", text: "Row text", selector: "button" } — child within container
+
+**Asserting text presence/absence** — DON'T write evaluate with body.includes():
+  assert_text:     { type: "assert_text", text: "Welcome" }      — text IS on page (case-sensitive). Uses: text
+  assert_no_text:  { type: "assert_no_text", text: "Error" }     — text is NOT on page. Uses: text
+  assert_text_in:  { type: "assert_text_in", selector: "[class*='Drawer']", text: "profesional|doctor" }
+                   — scoped regex in container (case-insensitive default). Uses: selector + text (+ value:"exact")
+
+**Asserting elements** — DON'T write evaluate to count or check visibility:
+  assert_visible:      { type: "assert_visible", selector: ".modal" }           — Uses: selector (NOT text)
+  assert_not_visible:  { type: "assert_not_visible", selector: ".loader" }      — Uses: selector (NOT text)
+  assert_count:        { type: "assert_count", selector: "input", value: ">= 2" } — Uses: selector + value
+  assert_element_text: { type: "assert_element_text", selector: "h1", text: "Dashboard" } — Uses: selector + text
+  assert_matches:      { type: "assert_matches", selector: ".date", value: "\\\\d{2}/\\\\d{2}" } — Uses: selector + value (regex)
+  assert_attribute:    { type: "assert_attribute", selector: "button", value: "disabled" } — Uses: selector + value
+  assert_url:          { type: "assert_url", value: "/dashboard" }              — Uses: value
+  assert_input_value:  { type: "assert_input_value", selector: "#email", value: "@" } — Uses: selector + value
+
+IMPORTANT field rules:
+  - assert_text / assert_no_text: use "text" field only (checks full page body)
+  - assert_visible / assert_not_visible: use "selector" field only (CSS selector, NOT text)
+  - To verify text absence: use assert_no_text (NOT assert_not_visible with text)
+
+**Navigation & waiting** — DON'T write evaluate with setTimeout polling:
+  goto:            { type: "goto", value: "/login" }              — full page navigation
+  navigate:        { type: "navigate", value: "/settings" }       — SPA-friendly (won't fail if no page load)
+  wait:            { type: "wait", text: "Loading complete" }     — wait for text to appear in body
+  wait:            { type: "wait", selector: ".results" }         — wait for element to appear
+  wait:            { type: "wait", value: "2000" }                — fixed delay (avoid when possible)
+  wait_network_idle: { type: "wait_network_idle", value: "500" }  — wait until no network for N ms
+
+**Form interaction** — DON'T write evaluate with native value setters (unless React):
+  type:            { type: "type", selector: "#email", value: "a@b.com" } — clears + types
+  type_react:      { type: "type_react", selector: "#email", value: "a@b.com" } — for React controlled inputs
+  select:          { type: "select", selector: "select#country", value: "US" }
+  clear:           { type: "clear", selector: "#search" }
+  press:           { type: "press", value: "Enter" }
+  focus_autocomplete: { type: "focus_autocomplete", text: "City" } — focus MUI Autocomplete by label
+
+**When evaluate IS appropriate**: computed styles, complex conditional logic, GraphQL via window.__e2eGql, math calculations, reading window/app state.
+
+## Modules
+Use { "$use": "module-name", "params": {...} } to reference reusable modules from e2e/modules/. Modules compose — a module can $use other modules. Check e2e_list to see available modules for the project.`,
     inputSchema: {
       type: 'object',
       properties: {
         name: {
           type: 'string',
-          description: 'Suite file name without .json extension (e.g. "login", "05-checkout")',
+          description: 'Suite file name without .json extension (e.g. "login-flow", "issue-1743-sidebar")',
         },
         tests: {
           type: 'array',
-          description: 'Array of test objects with { name, actions }',
+          description: 'Array of test objects with { name, actions, expect }',
           items: {
             type: 'object',
             properties: {
-              name: { type: 'string', description: 'Test name' },
-              expect: { type: 'string', description: 'Human-readable description of the expected visual outcome. After the test runs, a verification screenshot is captured and Claude Code judges pass/fail against this description.' },
+              name: { type: 'string', description: 'Test name — descriptive of what is being verified' },
+              expect: {
+                oneOf: [
+                  { type: 'string', description: 'Single description of expected visual outcome.' },
+                  { type: 'array', items: { type: 'string' }, description: 'Checklist of criteria — each evaluated independently as PASS/FAIL.' },
+                ],
+                description: 'Expected visual outcome. String for free-form, array for per-criterion checklist.',
+              },
               actions: {
                 type: 'array',
-                description: 'Sequential browser actions',
+                description: 'Sequential browser actions. Prefer built-in action types over evaluate — see tool description for the full guide.',
                 items: {
                   type: 'object',
                   properties: {
                     type: {
                       type: 'string',
-                      description: 'Action type: goto, click, click_regex, click_option, click_chip, type, type_react, focus_autocomplete, wait, assert_text, assert_element_text, assert_attribute, assert_class, assert_visible, assert_not_visible, assert_input_value, assert_matches, assert_url, assert_count, assert_no_network_errors, get_text, screenshot, select, clear, clear_cookies, press, scroll, hover, evaluate, navigate',
+                      description: 'Action type. Prefer declarative actions (assert_text, assert_no_text, click, assert_visible, assert_count, assert_text_in, click_menu_item, etc.) over evaluate.',
                     },
-                    selector: { type: 'string', description: 'CSS selector' },
-                    value: { type: 'string', description: 'Value for the action' },
-                    text: { type: 'string', description: 'Text content to match' },
+                    selector: { type: 'string', description: 'CSS selector (supports compound selectors like "[class*=\'Drawer\'], [role=\'presentation\']")' },
+                    value: { type: 'string', description: 'Value — varies by action type (URL for goto, ms for wait, regex for assert_matches, ">= N" for assert_count)' },
+                    text: { type: 'string', description: 'Text to match — used by click (substring), assert_text/assert_no_text (substring on body), assert_text_in (regex), click_regex (regex). NOT used by assert_visible/assert_not_visible (use selector instead).' },
                   },
                   required: ['type'],
                 },
@@ -128,7 +223,7 @@ export const TOOLS = [
         },
         hooks: {
           type: 'object',
-          description: 'Optional hooks: beforeAll, afterAll, beforeEach, afterEach (each an array of actions)',
+          description: 'Optional hooks: beforeAll, afterAll, beforeEach, afterEach (each an array of actions). Note: beforeAll runs on a SEPARATE page that is closed before tests — use beforeEach for auth/setup.',
           properties: {
             beforeAll: { type: 'array', items: { type: 'object' } },
             afterAll: { type: 'array', items: { type: 'object' } },
@@ -158,6 +253,20 @@ export const TOOLS = [
       },
     },
   },
+  {
+    name: 'e2e_app_pool_status',
+    description:
+      'Get the status of the app environment pool. Shows active forks, allocated ports, per-fork details (driver, baseUrl, test name, fork time). Only relevant when appPool is enabled in config.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        cwd: {
+          type: 'string',
+          description: 'Absolute path to the project root directory.',
+        },
+      },
+    },
+  },
   {
     name: 'e2e_screenshot',
     description:
@@ -199,6 +308,24 @@ export const TOOLS = [
       properties: {},
     },
   },
+  {
+    name: 'e2e_dashboard_restart',
+    description:
+      'Restart the E2E Runner web dashboard. Stops the current instance and starts a new one, optionally with a new cwd or port. Useful when switching projects or when the dashboard was started from another session.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        port: {
+          type: 'number',
+          description: 'Dashboard port (default: same port or 8484)',
+        },
+        cwd: {
+          type: 'string',
+          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+        },
+      },
+    },
+  },
   {
     name: 'e2e_issue',
     description:
@@ -272,6 +399,63 @@ export const TOOLS = [
           type: 'string',
           description: 'localStorage key name for the auth token (default: "accessToken")',
         },
+        waitUntil: {
+          type: 'string',
+          enum: ['networkidle2', 'domcontentloaded', 'load', 'auto'],
+          description: 'Navigation wait strategy. "auto" (default) tries networkidle2 first with a short timeout, then falls back to domcontentloaded + delay for SPA/WebSocket apps. Use "domcontentloaded" for apps with persistent connections (WebSocket, SSE).',
+        },
+        cwd: {
+          type: 'string',
+          description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
+        },
+      },
+      required: ['url'],
+    },
+  },
+  {
+    name: 'e2e_analyze',
+    description:
+      'Analyze a page\'s structure and return all interactive elements (forms, buttons, links, navigation, tables, modals, etc.) with their CSS selectors, plus suggested test scaffolds. One call replaces the entire screenshot→guess-selectors→retry cycle.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        url: {
+          type: 'string',
+          description: 'Full URL to analyze (e.g. "https://example.com" or "http://host.docker.internal:3000/dashboard")',
+        },
+        scope: {
+          type: 'string',
+          description: 'CSS selector to limit analysis to a section (e.g. "#sidebar", ".modal-content")',
+        },
+        maxElements: {
+          type: 'number',
+          description: 'Max elements per category (default: 50). Lower values produce smaller responses.',
+        },
+        includeScreenshot: {
+          type: 'boolean',
+          description: 'Include a screenshot alongside the JSON analysis (default: true)',
+        },
+        selector: {
+          type: 'string',
+          description: 'Wait for this CSS selector before analyzing',
+        },
+        delay: {
+          type: 'number',
+          description: 'Wait N milliseconds after page load before analyzing (default: 0)',
+        },
+        authToken: {
+          type: 'string',
+          description: 'JWT or auth token to inject into localStorage before navigating (for authenticated pages)',
+        },
+        authStorageKey: {
+          type: 'string',
+          description: 'localStorage key name for the auth token (default: "accessToken")',
+        },
+        waitUntil: {
+          type: 'string',
+          enum: ['networkidle2', 'domcontentloaded', 'load', 'auto'],
+          description: 'Navigation wait strategy. "auto" (default) tries networkidle2 first with a short timeout, then falls back to domcontentloaded + delay for SPA/WebSocket apps. Use "domcontentloaded" for apps with persistent connections (WebSocket, SSE).',
+        },
         cwd: {
           type: 'string',
           description: 'Absolute path to the project root directory. Claude Code should pass its current working directory.',
@@ -283,7 +467,9 @@ export const TOOLS = [
   {
     name: 'e2e_create_module',
     description:
-      'Create a reusable module for E2E tests. Modules define action sequences that can be referenced from tests via { "$use": "module-name", "params": {...} }. Useful for auth setup, navigation patterns, and other repeated sequences.',
+      `Create a reusable module for E2E tests. Modules encapsulate repeated action sequences referenced via { "$use": "module-name", "params": {...} }.
+
+Good module candidates: auth setup, page navigation, tab clicking, opening sidebars/drawers, form fill sequences, cleanup routines. Modules can compose — a module can $use other modules. Params use {{paramName}} mustache syntax in action fields. Extract a module when you see the same 2+ action sequence in multiple tests.`,
     inputSchema: {
       type: 'object',
       properties: {
@@ -420,11 +606,43 @@ export const TOOLS = [
       required: ['runDbId'],
     },
   },
+  {
+    name: 'e2e_vars',
+    description:
+      'Manage project variables stored in SQLite. Variables can be referenced in test JSON as {{var.KEY}}. Supports project-wide and per-suite scoping.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        action: {
+          type: 'string',
+          enum: ['set', 'get', 'list', 'delete'],
+          description: 'Action to perform: set (upsert), get (one key), list (all), delete',
+        },
+        key: {
+          type: 'string',
+          description: 'Variable name (required for set, get, delete)',
+        },
+        value: {
+          type: 'string',
+          description: 'Variable value (required for set)',
+        },
+        scope: {
+          type: 'string',
+          description: 'Scope: "project" (default) or a suite name for suite-specific override',
+        },
+        cwd: {
+          type: 'string',
+          description: 'Absolute path to the project root directory.',
+        },
+      },
+      required: ['action'],
+    },
+  },
 ];
 
-/** Tools exposed on the dashboard — excludes dashboard start/stop (already running). */
+/** Tools exposed on the dashboard — excludes dashboard start/stop/restart (already running). */
 export const DASHBOARD_TOOLS = TOOLS.filter(
-  t => t.name !== 'e2e_dashboard_start' && t.name !== 'e2e_dashboard_stop'
+  t => t.name !== 'e2e_dashboard_start' && t.name !== 'e2e_dashboard_stop' && t.name !== 'e2e_dashboard_restart'
 );
 
 // ── Dashboard broadcast helper ────────────────────────────────────────────────
@@ -469,11 +687,13 @@ async function handleRun(args) {
   if (args.baseUrl) configOverrides.baseUrl = args.baseUrl;
   if (args.retries !== undefined) configOverrides.retries = args.retries;
   if (args.failOnNetworkError !== undefined) configOverrides.failOnNetworkError = args.failOnNetworkError;
+  if (args.verificationStrictness) configOverrides.verificationStrictness = args.verificationStrictness;
 
   const config = await loadConfig(configOverrides, args.cwd);
   config.triggeredBy = 'mcp';
 
-  await waitForPool(config.poolUrl);
+  const driverOpts = { poolDriver: config.poolDriver, maxSessions: config.maxSessions };
+  await waitForAnyPool(getPoolUrls(config), 30000, driverOpts);
 
   let tests, hooks;
 
@@ -506,7 +726,12 @@ async function handleRun(args) {
 
   const report = generateReport(results);
   saveReport(report, config.screenshotsDir, config);
-  const { runDbId } = persistRun(report, config, args.suite || null);
+  // Derive suite name: explicit suite > file basename > null (for "all")
+  let suiteName = args.suite || null;
+  if (!suiteName && args.file) {
+    suiteName = path.basename(args.file, '.json');
+  }
+  const { runDbId } = await persistRun(report, config, suiteName);
 
   const failures = report.results
     .filter(r => !r.success)
@@ -517,8 +742,13 @@ async function handleRun(args) {
     }));
 
   const flaky = report.results
-    .filter(r => r.success && r.attempt > 1)
-    .map(r => ({ name: r.name, attempts: r.attempt }));
+    .filter(r => r.success && (r.attempt > 1 || r.flaky))
+    .map(r => {
+      const entry = { name: r.name };
+      if (r.voting) entry.voting = r.voting;
+      else entry.attempts = r.attempt;
+      return entry;
+    });
 
   const summary = {
     ...report.summary,
@@ -563,12 +793,21 @@ async function handleRun(args) {
 
   const verifications = report.results
     .filter(r => r.expect && r.verificationScreenshot)
-    .map(r => ({
-      name: r.name,
-      expect: r.expect,
-      success: r.success,
-      screenshotHash: 'ss:' + computeScreenshotHash(r.verificationScreenshot),
-    }));
+    .map(r => {
+      const entry = {
+        name: r.name,
+        expect: r.expect,
+        success: r.success,
+        screenshotHash: 'ss:' + computeScreenshotHash(r.verificationScreenshot),
+      };
+      if (r.baselineScreenshot) {
+        entry.baselineScreenshotHash = 'ss:' + computeScreenshotHash(r.baselineScreenshot);
+      }
+      if (Array.isArray(r.expect)) {
+        entry.isChecklist = true;
+      }
+      return entry;
+    });
 
   if (flaky.length > 0) summary.flaky = flaky;
   if (failures.length > 0) summary.failures = failures;
@@ -590,7 +829,9 @@ async function handleRun(args) {
   }
   if (verifications.length > 0) {
     summary.verifications = verifications;
-    summary.verificationInstructions = 'For each verification, call e2e_screenshot with the screenshotHash to view the screenshot. Then compare what you see against the "expect" description. Report any mismatches as FAIL.';
+    const hasBaselines = verifications.some(v => v.baselineScreenshotHash);
+    const hasChecklists = verifications.some(v => v.isChecklist);
+    summary.verificationInstructions = buildVerificationInstructions(config.verificationStrictness || 'moderate', hasBaselines, hasChecklists);
   }
 
   // Build per-test narrative: a step-by-step human-readable story of what happened
@@ -601,10 +842,19 @@ async function handleRun(args) {
   }));
   if (narratives.length > 0) summary.narratives = narratives;
 
-  // Enrich with learning insights (fire-and-forget — never fails the response)
+  // Enrich with learning insights + health snapshot (fire-and-forget — never fails the response)
   if (config.learningsEnabled !== false) {
     try {
       const projectId = ensureProject(config._cwd, config.projectName, config.screenshotsDir, config.testsDir);
+
+      // Always include health snapshot (~200 bytes) for project context
+      const health = getHealthSnapshot(projectId);
+      if (health) {
+        summary.healthSnapshot = health;
+        summary.learningsHint = "Use e2e_learnings tool with query 'summary' for full analysis.";
+      }
+
+      // Contextual insights for this specific run
       const insights = getRunInsights(projectId, report);
       if (insights.length > 0) {
         summary.learnings = {
@@ -618,6 +868,25 @@ async function handleRun(args) {
             : null,
         };
       }
+
+      // Actionable improvements from cross-referencing this run with historical data
+      const improvements = generateImprovements(projectId, report);
+      if (improvements.length > 0) {
+        summary.improvements = improvements;
+      }
+    } catch { /* never fail the run response */ }
+  }
+
+  // Hindsight hints — LLM-powered fix suggestions for failures (async, never blocks)
+  if (hasApiKey(config) && failures.length > 0) {
+    try {
+      const maxHints = config.hintsMaxFailures ?? 3;
+      const hintTargets = failures.slice(0, maxHints);
+      const failedResults = hintTargets.map(f => report.results.find(r => r.name === f.name)).filter(Boolean);
+      const hints = (await Promise.all(failedResults.map(r => generateHindsightHint(r, config)))).filter(Boolean);
+      if (hints.length > 0) {
+        summary.hindsightHints = hints;
+      }
     } catch { /* never fail the run response */ }
   }
 
@@ -660,6 +929,14 @@ async function handleCreateTest(args) {
   }
 
   const safeName = path.basename(args.name);
+
+  // Reject generic/ambiguous suite names
+  const baseName = safeName.replace(/\.json$/, '').replace(/^\d+-/, '');
+  const FORBIDDEN_NAMES = ['all', 'test', 'tests', 'debug', 'new', 'temp', 'tmp', 'main', 'suite', 'run', 'e2e', 'default', 'untitled'];
+  if (FORBIDDEN_NAMES.includes(baseName.toLowerCase())) {
+    return errorResult(`Suite name "${baseName}" is too generic. Use a descriptive name specific to the feature or issue being tested (e.g. "login-valid-credentials", "issue-1743-auth-redirect").`);
+  }
+
   const filename = safeName.endsWith('.json') ? safeName : `${safeName}.json`;
   const filePath = path.join(config.testsDir, filename);
 
@@ -676,36 +953,361 @@ async function handleCreateTest(args) {
 
   fs.writeFileSync(filePath, JSON.stringify(content, null, 2) + '\n');
 
-  // Warn about beforeAll pitfall
-  let warning = '';
+  // ── Collect all actions (tests + hooks) for analysis ──
+  const allActions = [];
+  for (const test of args.tests) {
+    if (test.actions) allActions.push(...test.actions);
+  }
+  if (args.hooks) {
+    for (const hookActions of Object.values(args.hooks)) {
+      if (Array.isArray(hookActions)) allActions.push(...hookActions);
+    }
+  }
+
+  const warnings = [];
+
+  // ── Warn about beforeAll pitfall ──
   const beforeAll = args.hooks?.beforeAll;
   if (beforeAll?.length) {
     const stateActions = beforeAll.filter(a =>
       ['evaluate', 'goto', 'navigate', 'clear_cookies', 'type', 'click', 'select'].includes(a.type)
     );
     if (stateActions.length > 0) {
-      warning = '\n\n⚠️ Warning: beforeAll runs on a separate browser page that is closed before tests start. ' +
-        'Actions that set browser state (evaluate, goto, cookies, etc.) will NOT carry over to individual tests. ' +
-        'Use beforeEach instead if tests need this setup.';
+      warnings.push('⚠️ beforeAll runs on a separate browser page that is closed before tests start. ' +
+        'Actions that set browser state (evaluate, goto, cookies, etc.) will NOT carry over. ' +
+        'Use beforeEach instead if tests need this setup.');
     }
   }
 
-  return textResult(`Created test file: ${filePath}\n\n${args.tests.length} test(s) defined.${warning}`);
+  // ── Detect evaluate blocks that could use built-in actions ──
+  const suggestions = analyzeEvaluateUsage(allActions);
+  if (suggestions.length > 0) {
+    warnings.push(`💡 ${suggestions.length} evaluate action(s) could potentially use built-in actions instead:\n` +
+      suggestions.map(s => `   • ${s}`).join('\n'));
+  }
+
+  // ── Detect suite-level issues: fixed waits, cross-test dependencies ──
+  const actionWarnings = analyzeActionPatterns(args.tests);
+  if (actionWarnings.length > 0) {
+    warnings.push(...actionWarnings);
+  }
+
+  // ── List available modules ──
+  let modulesInfo = '';
+  try {
+    const modules = listModules(config.modulesDir);
+    if (modules.length > 0) {
+      modulesInfo = '\n\n📦 Available modules: ' + modules.map(m => {
+        const params = m.params.filter(p => p.required).map(p => p.name);
+        return m.name + (params.length ? `(${params.join(', ')})` : '');
+      }).join(', ');
+    }
+  } catch { /* modules dir may not exist */ }
+
+  const warningBlock = warnings.length > 0 ? '\n\n' + warnings.join('\n\n') : '';
+
+  // Enrich with learnings context for smarter test authoring
+  let learningsBlock = '';
+  try {
+    const projectId = ensureProject(config._cwd, config.projectName, config.screenshotsDir, config.testsDir);
+    const ctx = getTestCreationContext(projectId);
+    if (ctx) {
+      const lines = ['\n\n⚠ LEARNINGS FROM PREVIOUS RUNS:'];
+
+      if (ctx.unstableSelectors?.length) {
+        lines.push('  Unstable selectors (avoid these):');
+        for (const s of ctx.unstableSelectors) {
+          lines.push(`    - ${s.selector} (${s.failRate}% fail rate) → ${s.suggestion}`);
+        }
+      }
+
+      if (ctx.errorPatterns?.length) {
+        lines.push('  Common errors:');
+        for (const e of ctx.errorPatterns) {
+          lines.push(`    - ${e.category || 'unknown'} (${e.count}x) — ${e.pattern}`);
+        }
+      }
+
+      if (ctx.slowPages?.length) {
+        lines.push('  Slow pages (add extra waits):');
+        for (const p of ctx.slowPages) {
+          lines.push(`    - ${p.page} (avg ${(p.avgLoadMs / 1000).toFixed(1)}s load)`);
+        }
+      }
+
+      if (ctx.stableSelectors?.length) {
+        lines.push('  Reliable selectors (safe to use):');
+        for (const s of ctx.stableSelectors) {
+          lines.push(`    - ${s.selector} (100% success, ${s.uses} uses)`);
+        }
+      }
+
+      if (ctx.flakyTests?.length) {
+        lines.push('  Flaky tests (consider retries):');
+        for (const f of ctx.flakyTests) {
+          lines.push(`    - ${f.name} (${f.flakyCount} flaky runs out of ${f.totalRuns})`);
+        }
+      }
+
+      if (ctx.apiIssues?.length) {
+        lines.push('  Unreliable API endpoints:');
+        for (const a of ctx.apiIssues) {
+          lines.push(`    - ${a.endpoint} (${a.errorRate}% error rate)`);
+        }
+      }
+
+      if (ctx.passRate !== undefined) {
+        lines.push(`  Overall project pass rate: ${ctx.passRate}%`);
+      }
+
+      learningsBlock = lines.join('\n');
+    }
+  } catch { /* never fail test creation */ }
+
+  return textResult(`Created test file: ${filePath}\n\n${args.tests.length} test(s) defined.${warningBlock}${modulesInfo}${learningsBlock}`);
+}
+
+/**
+ * Analyze evaluate actions and suggest built-in replacements.
+ * Returns an array of human-readable suggestion strings.
+ */
+function analyzeEvaluateUsage(actions) {
+  const suggestions = [];
+
+  for (const action of actions) {
+    if (action.type !== 'evaluate' || !action.value) continue;
+    const code = action.value;
+
+    // Pattern: clicking elements by text — .click() after finding by textContent
+    if (/\.textContent[^]*\.click\(\)/s.test(code) || /\.find\([^)]*textContent[^)]*\)[^]*\.click/s.test(code)) {
+      if (/tab/i.test(code)) {
+        suggestions.push('Tab click via evaluate → use { type: "click", text: "Tab Name" } (click searches [role="tab"] natively)');
+      } else if (/menu/i.test(code)) {
+        suggestions.push('Menu item click via evaluate → use { type: "click_menu_item", text: "Item Name" }');
+      } else {
+        suggestions.push('Element click via evaluate → use { type: "click", text: "..." } or click_regex/click_in_context');
+      }
+    }
+
+    // Pattern: body.innerText.includes() for text presence
+    if (/document\.body\.innerText[^]*\.includes\(/s.test(code) || /body\.includes\(/s.test(code)) {
+      // Detect negation patterns (!includes) that should use assert_no_text
+      const hasNegation = /!\s*body\.includes\(|!\s*\w+\.includes\(|!body\.includes\(/s.test(code)
+        || /=\s*!.*\.includes\(/s.test(code);
+      const includeCount = (code.match(/\.includes\(/g) || []).length;
+
+      if (hasNegation) {
+        suggestions.push(`🚨 Text negation check (!includes) → use { type: "assert_no_text", text: "..." } for absent text, and { type: "assert_text", text: "..." } for present text`);
+      } else if (includeCount <= 3) {
+        suggestions.push(`Text presence check (${includeCount} includes) → use ${includeCount}x { type: "assert_text", text: "..." }`);
+      } else {
+        suggestions.push(`Text presence check (${includeCount} includes) → use assert_text for each, or assert_text_in with regex: { type: "assert_text_in", selector: "body", text: "word1|word2" }`);
+      }
+    }
+
+    // Pattern: querySelectorAll(...).length checks
+    if (/querySelectorAll\([^)]+\)\.length/s.test(code) && !/getComputedStyle/.test(code)) {
+      suggestions.push('Element counting via evaluate → use { type: "assert_count", selector: "...", value: ">= N" }');
+    }
+
+    // Pattern: checking element visibility/existence without computed styles
+    if (/querySelector\([^)]+\)\s*;?\s*(if\s*\(!\s*\w+\)|===?\s*null)/s.test(code) && !/getComputedStyle/.test(code)) {
+      suggestions.push('Element existence check via evaluate → use { type: "assert_visible", selector: "..." }');
+    }
+
+    // Pattern: return JSON.stringify for debug info (no throw/Error)
+    if (/return\s+JSON\.stringify/s.test(code) && !/throw\s+new\s+Error/s.test(code) && !/FAIL/s.test(code)) {
+      suggestions.push('Informational evaluate (returns JSON, never throws) → remove or replace with specific assertions');
+    }
+
+    // Pattern: setTimeout polling loop
+    if (/setTimeout|setInterval/s.test(code) && /while|Date\.now/s.test(code)) {
+      suggestions.push('Polling loop in evaluate → use { type: "wait", text: "..." } or { type: "wait", selector: "..." } with timeout');
+    }
+
+    // Pattern: return static string with no checks
+    if (/^\(\(\)\s*=>\s*\{\s*return\s+['"`][^]*['"`];\s*\}\)\(\)$/.test(code.trim())) {
+      suggestions.push('No-op evaluate (returns static string) → remove entirely');
+    }
+
+    // 🚨 Pattern: evaluate that NEVER fails — no throw, no FAIL:/ERROR:, no return false
+    const canFail = /throw\s+new\s+Error/s.test(code) || /\bFAIL[:\s]/s.test(code) || /\bERROR[:\s]/s.test(code)
+      || /return\s+false\b/s.test(code) || /return\s+'FAIL/s.test(code) || /return\s+`FAIL/s.test(code);
+
+    if (!canFail) {
+      // Any template string return → always truthy, test always passes
+      if (/return\s+`[^`]*\$\{[^}]+\}[^`]*`/s.test(code)) {
+        suggestions.push(
+          '🚨 Evaluate returns template string but NEVER throws or returns false — ' +
+          'this action will ALWAYS PASS regardless of results. Either throw new Error("FAIL: ...") when conditions fail, or use built-in assert actions'
+        );
+      }
+      // Returns a plain string (not template) that isn't FAIL/ERROR
+      else if (/return\s+['"][^'"]*['"]/s.test(code) && code.length > 60) {
+        suggestions.push(
+          '⚠️ Evaluate returns a plain string but never fails — informational-only. Add failure conditions or replace with assert actions'
+        );
+      }
+    }
+
+    // 🚨 Pattern: .click() inside evaluate — should use built-in click action
+    if (/\.click\(\)/s.test(code) && !(/\.textContent[^]*\.click\(\)/s.test(code))) {
+      // Only flag if not already caught by the textContent click pattern above
+      if (/\.filter\([^)]*text/s.test(code) || /querySelectorAll[^)]*\)[^]*\.click/s.test(code) || /querySelector[^)]*\)[^]*\.click/s.test(code)) {
+        suggestions.push(
+          '🚨 Element click via evaluate → use { type: "click", text: "..." } or { type: "click", selector: "..." }. ' +
+          'Built-in click has retries, waits, and better error reporting'
+        );
+      }
+    }
+
+    // 🚨 Pattern: MUI/framework selectors inside evaluate — fragile
+    const muiMatches = code.match(/\.Mui[\w-]+/g) || [];
+    if (muiMatches.length > 0) {
+      suggestions.push(
+        `⚠️ MUI class selectors (${muiMatches.slice(0, 3).join(', ')}) are auto-generated and change between versions. ` +
+        `Prefer [data-testid="..."], [role="..."], or text-based selectors`
+      );
+    }
+
+    // 🚨 Pattern: sets window.__e2e_* globals for cross-test state sharing
+    if (/window\.__e2e_\w+\s*=/.test(code) && !/window\.__e2e\./.test(code.replace(/window\.__e2e_\w+\s*=/g, ''))) {
+      suggestions.push(
+        '⚠️ Cross-test state via window.__e2e_* — if test retries are enabled, retried tests get a fresh page and lose this state. ' +
+        'Make each test self-contained by re-querying data, or disable retries for this suite'
+      );
+    }
+  }
+
+  return suggestions;
+}
+
+/**
+ * Analyze all actions in a suite for non-evaluate issues:
+ * fixed numeric waits, cross-test dependencies, etc.
+ */
+function analyzeActionPatterns(tests) {
+  const warnings = [];
+
+  // Detect fixed numeric waits (could be text/selector-based)
+  for (const test of tests) {
+    if (!test.actions) continue;
+    for (const action of test.actions) {
+      if (action.type === 'wait' && /^\d+$/.test(String(action.value))) {
+        const ms = parseInt(action.value, 10);
+        if (ms >= 3000) {
+          warnings.push(
+            `⏱️ Fixed ${ms}ms wait in "${test.name}" — prefer { type: "wait", text: "..." } or { type: "wait", selector: "..." } ` +
+            `which retries until the condition is met. Fixed waits are either too short (flaky) or too long (slow).`
+          );
+          break; // one warning per test is enough
+        }
+      }
+    }
+  }
+
+  // Detect MUI/framework selectors in action selectors
+  for (const test of tests) {
+    if (!test.actions) continue;
+    for (const action of test.actions) {
+      const sel = action.selector || '';
+      if (/\.Mui[\w-]+/.test(sel) || /\.ant-[\w-]+/.test(sel) || /\.v-[\w-]+/.test(sel)) {
+        const match = sel.match(/\.(Mui[\w-]+|ant-[\w-]+|v-[\w-]+)/);
+        warnings.push(
+          `⚠️ Framework selector ".${match[1]}" in "${test.name}" (${action.type}) — ` +
+          `these class names are auto-generated and break on version upgrades. ` +
+          `Prefer [data-testid="..."], [role="..."], or text-based actions`
+        );
+        break;
+      }
+    }
+  }
+
+  // Detect cross-test state: test N writes window.__e2e_*, test M reads it
+  const writers = new Map(); // varName → test name
+  const readers = new Map(); // varName → [test names]
+  for (const test of tests) {
+    if (!test.actions) continue;
+    for (const action of test.actions) {
+      if (action.type !== 'evaluate' || !action.value) continue;
+      const code = action.value;
+      // Find writes: window.__e2e_foo = ...
+      const writeMatches = code.matchAll(/window\.(__e2e_\w+)\s*=/g);
+      for (const m of writeMatches) {
+        if (!writers.has(m[1])) writers.set(m[1], test.name);
+      }
+      // Find reads: window.__e2e_foo (not followed by =)
+      const readMatches = code.matchAll(/window\.(__e2e_\w+)(?!\s*=)/g);
+      for (const m of readMatches) {
+        if (!readers.has(m[1])) readers.set(m[1], []);
+        if (!readers.get(m[1]).includes(test.name)) readers.get(m[1]).push(test.name);
+      }
+    }
+  }
+
+  for (const [varName, writerTest] of writers) {
+    const readerTests = (readers.get(varName) || []).filter(t => t !== writerTest);
+    if (readerTests.length > 0) {
+      warnings.push(
+        `🔗 Cross-test dependency: "${writerTest}" sets ${varName}, read by: ${readerTests.map(t => `"${t}"`).join(', ')}. ` +
+        `If "${writerTest}" fails, dependent tests will cascade-fail with confusing errors. ` +
+        `Consider re-querying data in each test or combining them into a single test.`
+      );
+    }
+  }
+
+  return warnings;
 }
 
 async function handlePoolStatus(args) {
   const config = await loadConfig({}, args.cwd);
-  const status = await getPoolStatus(config.poolUrl);
+  const poolUrls = getPoolUrls(config);
+  const aggregated = await getAggregatedPoolStatus(poolUrls, { poolDriver: config.poolDriver, maxSessions: config.maxSessions });
+
+  const lines = [];
 
+  if (poolUrls.length > 1) {
+    lines.push(`Pools:     ${aggregated.totalPools} (${aggregated.availableCount} available)`);
+    lines.push(`Running:   ${aggregated.totalRunning}/${aggregated.totalMaxConcurrent}`);
+    lines.push(`Queued:    ${aggregated.totalQueued}`);
+    lines.push('');
+    for (const pool of aggregated.pools) {
+      const status = pool.available ? 'available' : pool.error ? `offline (${pool.error})` : 'busy';
+      lines.push(`  ${pool.url}: ${status} (${pool.running}/${pool.maxConcurrent}, ${pool.queued} queued)`);
+    }
+  } else {
+    const pool = aggregated.pools[0];
+    lines.push(`Available: ${pool.available ? 'yes' : 'no'}`);
+    lines.push(`Running:   ${pool.running}/${pool.maxConcurrent}`);
+    lines.push(`Queued:    ${pool.queued}`);
+    lines.push(`Sessions:  ${pool.sessions?.length ?? 0}`);
+    if (pool.error) {
+      lines.push(`Error:     ${pool.error}`);
+    }
+  }
+
+  return textResult(lines.join('\n'));
+}
+
+async function handleAppPoolStatus(args) {
+  const config = await loadConfig({}, args.cwd);
+  if (!isAppPoolEnabled(config)) {
+    return textResult('App pool is not enabled. Set appPool.enabled = true in e2e.config.js to use isolated app environments per test.');
+  }
+
+  const status = getAppPoolStatus();
   const lines = [
-    `Available: ${status.available ? 'yes' : 'no'}`,
-    `Running:   ${status.running}/${status.maxConcurrent}`,
-    `Queued:    ${status.queued}`,
-    `Sessions:  ${status.sessions.length}`,
+    `Driver:        ${config.appPool.driver}`,
+    `Active forks:  ${status.activeForks}/${config.appPool.maxForks}`,
+    `Port range:    ${config.appPool.forkBasePort}-${config.appPool.forkBasePort + config.appPool.maxForks - 1}`,
+    `Allocated:     ${status.allocatedPorts.length ? status.allocatedPorts.join(', ') : 'none'}`,
   ];
 
-  if (status.error) {
-    lines.push(`Error:     ${status.error}`);
+  if (status.forks.length > 0) {
+    lines.push('');
+    for (const fork of status.forks) {
+      lines.push(`  ${fork.forkId}: port ${fork.port}, ${fork.baseUrl} (${fork.testName || 'unnamed'}, ${fork.forkTimeMs}ms)`);
+    }
   }
 
   return textResult(lines.join('\n'));
@@ -831,21 +1433,556 @@ async function handleCreateModule(args) {
   return textResult(`Created module: ${filePath}\n\nName: ${args.name}\nParams: ${paramNames.length ? paramNames.join(', ') : 'none'}\nActions: ${args.actions.length}\n\nUsage in tests: { "$use": "${args.name}", "params": { ... } }`);
 }
 
-async function handleCapture(args) {
+// ── Page analysis helpers ─────────────────────────────────────────────────────
+
+/**
+ * Browser-side function passed to page.evaluate().
+ * Extracts the complete interactive structure of a page in a single DOM pass.
+ */
+function extractPageStructure(scopeSelector, maxElements) {
+  const MAX = maxElements || 50;
+  const root = scopeSelector ? document.querySelector(scopeSelector) : document.body;
+  if (!root) return { error: `Scope selector not found: ${scopeSelector}` };
+
+  // ── bestSelector: generate the most reliable CSS selector for an element ──
+  const FRAMEWORK_CLASS_RE = /^(css-|sc-|jss\d|Mui|emotion-|chakra-|ant-|el-|v-|ng-|_|svelte-|tw-)/;
+
+  function bestSelector(el) {
+    // 1. ID (if unique)
+    if (el.id && document.querySelectorAll(`#${CSS.escape(el.id)}`).length === 1) {
+      return `#${CSS.escape(el.id)}`;
+    }
+    // 2. data-testid
+    const testId = el.getAttribute('data-testid');
+    if (testId) return `[data-testid="${testId}"]`;
+    // 3. aria-label
+    const ariaLabel = el.getAttribute('aria-label');
+    if (ariaLabel && document.querySelectorAll(`[aria-label="${CSS.escape(ariaLabel)}"]`).length === 1) {
+      return `[aria-label="${CSS.escape(ariaLabel)}"]`;
+    }
+    // 4. name attribute
+    const name = el.getAttribute('name');
+    if (name && document.querySelectorAll(`[name="${CSS.escape(name)}"]`).length === 1) {
+      return `[name="${CSS.escape(name)}"]`;
+    }
+    // 5. Unique CSS class (filter framework-generated)
+    const tag = el.tagName.toLowerCase();
+    const classes = [...el.classList].filter(c => !FRAMEWORK_CLASS_RE.test(c));
+    for (const cls of classes) {
+      const sel = `${tag}.${CSS.escape(cls)}`;
+      if (document.querySelectorAll(sel).length === 1) return sel;
+    }
+    // 6. Two-class combination
+    for (let i = 0; i < classes.length; i++) {
+      for (let j = i + 1; j < classes.length; j++) {
+        const sel = `${tag}.${CSS.escape(classes[i])}.${CSS.escape(classes[j])}`;
+        if (document.querySelectorAll(sel).length === 1) return sel;
+      }
+    }
+    // 7. Parent with ID + tag:nth-of-type
+    let parent = el.parentElement;
+    while (parent && parent !== document.body) {
+      if (parent.id) {
+        const siblings = [...parent.querySelectorAll(`:scope > ${tag}`)];
+        const idx = siblings.indexOf(el);
+        if (idx !== -1) {
+          const sel = `#${CSS.escape(parent.id)} > ${tag}:nth-of-type(${idx + 1})`;
+          if (document.querySelectorAll(sel).length === 1) return sel;
+        }
+        break;
+      }
+      parent = parent.parentElement;
+    }
+    // 8. Fallback: tag:nth-of-type within parent
+    if (el.parentElement) {
+      const siblings = [...el.parentElement.querySelectorAll(`:scope > ${tag}`)];
+      const idx = siblings.indexOf(el);
+      if (idx !== -1) return `${tag}:nth-of-type(${idx + 1})`;
+    }
+    return tag;
+  }
+
+  function getLabel(el) {
+    // Check for associated label
+    if (el.id) {
+      const label = root.querySelector(`label[for="${CSS.escape(el.id)}"]`);
+      if (label) return label.textContent.trim();
+    }
+    // Check for wrapping label
+    const parentLabel = el.closest('label');
+    if (parentLabel) return parentLabel.textContent.trim();
+    // aria-label
+    if (el.getAttribute('aria-label')) return el.getAttribute('aria-label');
+    // placeholder
+    if (el.placeholder) return el.placeholder;
+    return '';
+  }
+
+  function isVisible(el) {
+    const style = getComputedStyle(el);
+    return style.display !== 'none' && style.visibility !== 'hidden' && style.opacity !== '0';
+  }
+
+  function truncate(arr) {
+    return arr.slice(0, MAX);
+  }
+
+  // ── Extract forms ──
+  const forms = [];
+  for (const form of root.querySelectorAll('form')) {
+    if (!isVisible(form)) continue;
+    const fields = [];
+    for (const input of form.querySelectorAll('input, select, textarea')) {
+      if (!isVisible(input) || input.type === 'hidden') continue;
+      fields.push({
+        selector: bestSelector(input),
+        tag: input.tagName.toLowerCase(),
+        type: input.type || input.tagName.toLowerCase(),
+        name: input.name || undefined,
+        label: getLabel(input) || undefined,
+        required: input.required || undefined,
+        placeholder: input.placeholder || undefined,
+      });
+    }
+    const submitBtn = form.querySelector('button[type="submit"], input[type="submit"]');
+    forms.push({
+      selector: bestSelector(form),
+      action: form.action || undefined,
+      method: form.method || undefined,
+      fields: truncate(fields),
+      submitButton: submitBtn ? { selector: bestSelector(submitBtn), text: submitBtn.textContent?.trim() || submitBtn.value } : undefined,
+    });
+    if (forms.length >= MAX) break;
+  }
+
+  // ── Standalone inputs (outside forms) ──
+  const standaloneInputs = [];
+  for (const input of root.querySelectorAll('input, select, textarea')) {
+    if (!isVisible(input) || input.type === 'hidden' || input.closest('form')) continue;
+    standaloneInputs.push({
+      selector: bestSelector(input),
+      tag: input.tagName.toLowerCase(),
+      type: input.type || input.tagName.toLowerCase(),
+      name: input.name || undefined,
+      label: getLabel(input) || undefined,
+      placeholder: input.placeholder || undefined,
+    });
+    if (standaloneInputs.length >= MAX) break;
+  }
+
+  // ── Buttons ──
+  const buttons = [];
+  for (const btn of root.querySelectorAll('button, [role="button"], input[type="button"], input[type="submit"]')) {
+    if (!isVisible(btn)) continue;
+    buttons.push({
+      selector: bestSelector(btn),
+      text: btn.textContent?.trim() || btn.value || '',
+      type: btn.type || undefined,
+      disabled: btn.disabled || undefined,
+      ariaLabel: btn.getAttribute('aria-label') || undefined,
+    });
+    if (buttons.length >= MAX) break;
+  }
+
+  // ── Links ──
+  const links = [];
+  for (const a of root.querySelectorAll('a[href]')) {
+    if (!isVisible(a)) continue;
+    links.push({
+      selector: bestSelector(a),
+      text: a.textContent?.trim() || '',
+      href: a.getAttribute('href'),
+    });
+    if (links.length >= MAX) break;
+  }
+
+  // ── Navigation regions ──
+  const navigation = [];
+  for (const nav of root.querySelectorAll('nav, [role="navigation"]')) {
+    if (!isVisible(nav)) continue;
+    const items = [];
+    for (const link of nav.querySelectorAll('a, button, [role="tab"], [role="menuitem"]')) {
+      if (!isVisible(link)) continue;
+      items.push({
+        selector: bestSelector(link),
+        text: link.textContent?.trim() || '',
+        href: link.getAttribute('href') || undefined,
+        active: link.classList.contains('active') || link.getAttribute('aria-current') === 'page' || undefined,
+      });
+    }
+    navigation.push({
+      selector: bestSelector(nav),
+      ariaLabel: nav.getAttribute('aria-label') || undefined,
+      items: truncate(items),
+    });
+    if (navigation.length >= MAX) break;
+  }
+
+  // ── Tabs ──
+  const tabs = [];
+  for (const tab of root.querySelectorAll('[role="tab"]')) {
+    if (!isVisible(tab)) continue;
+    tabs.push({
+      selector: bestSelector(tab),
+      text: tab.textContent?.trim() || '',
+      selected: tab.getAttribute('aria-selected') === 'true' || undefined,
+    });
+    if (tabs.length >= MAX) break;
+  }
+
+  // ── Headings ──
+  const headings = [];
+  for (const h of root.querySelectorAll('h1, h2, h3, h4, h5, h6')) {
+    if (!isVisible(h)) continue;
+    headings.push({
+      level: parseInt(h.tagName[1]),
+      text: h.textContent?.trim() || '',
+      selector: bestSelector(h),
+    });
+    if (headings.length >= MAX) break;
+  }
+
+  // ── Tables ──
+  const tables = [];
+  for (const table of root.querySelectorAll('table')) {
+    if (!isVisible(table)) continue;
+    const headers = [...table.querySelectorAll('th')].map(th => th.textContent?.trim());
+    tables.push({
+      selector: bestSelector(table),
+      headers: truncate(headers),
+      rowCount: table.querySelectorAll('tbody tr, tr').length,
+      hasHeader: headers.length > 0,
+    });
+    if (tables.length >= MAX) break;
+  }
+
+  // ── Modals/Dialogs ──
+  const modals = [];
+  for (const modal of root.querySelectorAll('[role="dialog"], dialog, .modal, [class*="modal"], [class*="Modal"]')) {
+    if (!isVisible(modal)) continue;
+    const title = modal.querySelector('[class*="title"], [class*="Title"], h1, h2, h3, [role="heading"]');
+    const closeBtn = modal.querySelector('[aria-label="close"], [aria-label="Close"], button.close, [class*="close"]');
+    modals.push({
+      selector: bestSelector(modal),
+      title: title?.textContent?.trim() || undefined,
+      hasCloseButton: !!closeBtn,
+      closeSelector: closeBtn ? bestSelector(closeBtn) : undefined,
+    });
+    if (modals.length >= MAX) break;
+  }
+
+  // ── Menus/Dropdowns ──
+  const menus = [];
+  for (const menu of root.querySelectorAll('[role="menu"], .dropdown-menu, [class*="dropdown"]')) {
+    if (!isVisible(menu)) continue;
+    const items = [];
+    for (const item of menu.querySelectorAll('[role="menuitem"], [role="menuitemradio"], [role="menuitemcheckbox"], .dropdown-item, [class*="MenuItem"]')) {
+      if (!isVisible(item)) continue;
+      items.push({ text: item.textContent?.trim() || '', selector: bestSelector(item) });
+    }
+    menus.push({
+      selector: bestSelector(menu),
+      items: truncate(items),
+    });
+    if (menus.length >= MAX) break;
+  }
+
+  // ── Alerts/Banners ──
+  const alerts = [];
+  for (const alert of root.querySelectorAll('[role="alert"], [role="status"], .alert, [class*="banner"], [class*="Banner"], [class*="toast"], [class*="Toast"], [class*="notification"], [class*="Notification"]')) {
+    if (!isVisible(alert)) continue;
+    alerts.push({
+      selector: bestSelector(alert),
+      text: alert.textContent?.trim().slice(0, 200) || '',
+      role: alert.getAttribute('role') || undefined,
+    });
+    if (alerts.length >= MAX) break;
+  }
+
+  // ── Significant images (>50px) ──
+  const images = [];
+  for (const img of root.querySelectorAll('img, svg[role="img"], [role="img"]')) {
+    if (!isVisible(img)) continue;
+    const rect = img.getBoundingClientRect();
+    if (rect.width < 50 && rect.height < 50) continue;
+    images.push({
+      selector: bestSelector(img),
+      alt: img.alt || img.getAttribute('aria-label') || undefined,
+      width: Math.round(rect.width),
+      height: Math.round(rect.height),
+      src: img.src ? img.src.slice(0, 200) : undefined,
+    });
+    if (images.length >= MAX) break;
+  }
+
+  return {
+    forms,
+    standaloneInputs: standaloneInputs.length > 0 ? standaloneInputs : undefined,
+    buttons,
+    links,
+    navigation: navigation.length > 0 ? navigation : undefined,
+    tabs: tabs.length > 0 ? tabs : undefined,
+    headings,
+    tables: tables.length > 0 ? tables : undefined,
+    modals: modals.length > 0 ? modals : undefined,
+    menus: menus.length > 0 ? menus : undefined,
+    alerts: alerts.length > 0 ? alerts : undefined,
+    images: images.length > 0 ? images : undefined,
+    stats: {
+      totalForms: forms.length,
+      totalButtons: buttons.length,
+      totalLinks: links.length,
+      totalInputs: forms.reduce((n, f) => n + f.fields.length, 0) + standaloneInputs.length,
+      totalHeadings: headings.length,
+      totalTables: tables.length,
+      totalNavRegions: navigation.length,
+      totalTabs: tabs.length,
+      totalModals: modals.length,
+      totalImages: images.length,
+    },
+  };
+}
+
+/**
+ * Analyzes extracted page structure and generates ready-to-use test scaffolds.
+ * Runs on the Node.js side after page.evaluate returns.
+ */
+function buildSuggestedTests(structure, pageUrl) {
+  const tests = [];
+  const urlPath = (() => { try { return new URL(pageUrl).pathname; } catch { return '/'; } })();
+
+  // Login form detection
+  for (const form of structure.forms || []) {
+    const fields = form.fields || [];
+    const hasPassword = fields.some(f => f.type === 'password');
+    const hasEmail = fields.some(f => f.type === 'email' || f.name === 'email' || (f.label || '').toLowerCase().includes('email'));
+    const hasUsername = fields.some(f => f.name === 'username' || (f.label || '').toLowerCase().includes('user'));
+
+    if (hasPassword && (hasEmail || hasUsername)) {
+      const actions = [{ type: 'goto', value: urlPath }];
+      const emailField = fields.find(f => f.type === 'email' || f.name === 'email' || (f.label || '').toLowerCase().includes('email'));
+      const usernameField = fields.find(f => f.name === 'username' || (f.label || '').toLowerCase().includes('user'));
+      const passwordField = fields.find(f => f.type === 'password');
+      const credential = emailField || usernameField;
+      if (credential) actions.push({ type: 'type', selector: credential.selector, value: 'test@example.com' });
+      if (passwordField) actions.push({ type: 'type', selector: passwordField.selector, value: 'password123' });
+      if (form.submitButton) actions.push({ type: 'click', selector: form.submitButton.selector });
+      actions.push({ type: 'wait', value: '2000' });
+      tests.push({ name: 'login-form-submission', actions });
+      continue;
+    }
+
+    // Generic form fill + submit
+    if (fields.length > 0) {
+      const actions = [{ type: 'goto', value: urlPath }];
+      for (const field of fields.slice(0, 10)) {
+        const val = field.type === 'email' ? 'test@example.com'
+          : field.type === 'number' ? '42'
+          : field.type === 'tel' ? '555-0100'
+          : field.type === 'date' ? '2025-01-15'
+          : field.tag === 'select' ? undefined
+          : field.tag === 'textarea' ? 'Sample text input'
+          : 'Test value';
+        if (val && field.tag !== 'select') {
+          actions.push({ type: 'type', selector: field.selector, value: val });
+        }
+      }
+      if (form.submitButton) actions.push({ type: 'click', selector: form.submitButton.selector });
+      actions.push({ type: 'wait', value: '1000' });
+      tests.push({ name: `form-submission-${tests.length + 1}`, actions });
+    }
+  }
+
+  // Navigation test
+  const navItems = (structure.navigation || []).flatMap(n => n.items || []).filter(i => i.href && i.text);
+  if (navItems.length > 0) {
+    const actions = [{ type: 'goto', value: urlPath }];
+    for (const item of navItems.slice(0, 5)) {
+      actions.push({ type: 'click', selector: item.selector });
+      actions.push({ type: 'wait', value: '1000' });
+      if (item.href && item.href !== '#' && !item.href.startsWith('javascript:')) {
+        actions.push({ type: 'assert_url', value: item.href });
+      }
+      actions.push({ type: 'goto', value: urlPath });
+    }
+    tests.push({ name: 'navigation-links', actions });
+  }
+
+  // Table data assertion
+  for (const table of structure.tables || []) {
+    if (table.rowCount > 0) {
+      tests.push({
+        name: `table-has-data`,
+        actions: [
+          { type: 'goto', value: urlPath },
+          { type: 'wait', selector: table.selector },
+          { type: 'assert_count', selector: `${table.selector} tbody tr`, value: '>=1' },
+        ],
+      });
+      break;
+    }
+  }
+
+  // Tab switching test
+  if ((structure.tabs || []).length >= 2) {
+    const actions = [{ type: 'goto', value: urlPath }];
+    for (const tab of structure.tabs.slice(0, 5)) {
+      actions.push({ type: 'click', selector: tab.selector });
+      actions.push({ type: 'wait', value: '500' });
+    }
+    tests.push({ name: 'tab-switching', actions });
+  }
+
+  // Page structure verification (always generated)
+  const verifyActions = [{ type: 'goto', value: urlPath }];
+  for (const h of (structure.headings || []).filter(h => h.level <= 2).slice(0, 3)) {
+    verifyActions.push({ type: 'assert_text', text: h.text });
+  }
+  if (structure.stats.totalButtons > 0) {
+    const visibleBtns = (structure.buttons || []).filter(b => b.text);
+    for (const btn of visibleBtns.slice(0, 3)) {
+      verifyActions.push({ type: 'assert_visible', selector: btn.selector });
+    }
+  }
+  tests.push({ name: 'page-structure-verification', actions: verifyActions });
+
+  return tests;
+}
+
+/**
+ * Smart page navigation with fallback for SPA/WebSocket apps.
+ * - "auto" (default): tries networkidle2 with 10s timeout, falls back to domcontentloaded + 2s delay
+ * - "networkidle2"/"load"/"domcontentloaded": uses that strategy directly with 30s timeout
+ */
+async function smartNavigate(page, url, waitUntil) {
+  const strategy = waitUntil || 'auto';
+
+  if (strategy === 'auto') {
+    try {
+      await page.goto(url, { waitUntil: 'networkidle2', timeout: 10000 });
+    } catch (err) {
+      if (err.name === 'TimeoutError' || (err.message && err.message.includes('timeout'))) {
+        // networkidle2 timed out — likely a SPA with WebSocket/SSE/polling
+        // Fall back to domcontentloaded + wait for hydration
+        await page.goto(url, { waitUntil: 'domcontentloaded', timeout: 20000 });
+        await new Promise(r => setTimeout(r, 2000));
+      } else {
+        throw err;
+      }
+    }
+  } else {
+    await page.goto(url, { waitUntil: strategy, timeout: 30000 });
+    // For domcontentloaded, add a small hydration delay for SPAs
+    if (strategy === 'domcontentloaded') {
+      await new Promise(r => setTimeout(r, 1500));
+    }
+  }
+}
+
+async function handleAnalyze(args) {
   if (!args.url) return errorResult('Missing required parameter: url');
 
   const config = await loadConfig({}, args.cwd);
+  const poolUrls = getPoolUrls(config);
+  const chosenPool = await selectPool(poolUrls, 2000, 60000, { poolDriver: config.poolDriver, maxSessions: config.maxSessions });
 
-  await waitForPool(config.poolUrl);
+  let browser;
+  try {
+    browser = await connectToPool(chosenPool);
+    const page = await browser.newPage();
+    await page.setViewport(config.viewport);
+
+    // Resolve auth token: explicit arg > config static > auto-login
+    const authToken = args.authToken || await resolveAuthToken(config);
+    if (authToken) {
+      const storageKey = args.authStorageKey || config.authStorageKey || 'accessToken';
+      const origin = new URL(args.url).origin;
+      await page.goto(origin, { waitUntil: 'domcontentloaded', timeout: 15000 });
+      await page.evaluate((key, token) => { localStorage.setItem(key, token); }, storageKey, authToken);
+    }
+
+    await smartNavigate(page, args.url, args.waitUntil);
+
+    if (args.selector) {
+      await page.waitForSelector(args.selector, { timeout: 10000 });
+    }
+
+    if (args.delay && args.delay > 0) {
+      await new Promise(r => setTimeout(r, args.delay));
+    }
+
+    // Extract page structure
+    const structure = await page.evaluate(extractPageStructure, args.scope || null, args.maxElements || 50);
+
+    if (structure.error) {
+      return errorResult(structure.error);
+    }
+
+    // Build meta
+    const title = await page.title();
+    const meta = {
+      url: args.url,
+      title,
+      viewport: config.viewport,
+      scope: args.scope || undefined,
+    };
+
+    // Build suggested tests
+    const suggestedTests = buildSuggestedTests(structure, args.url);
+
+    // Optional screenshot (default: true)
+    const includeScreenshot = args.includeScreenshot !== false;
+    let screenshotHash;
+    let screenshotBase64;
+
+    if (includeScreenshot) {
+      const filename = `analyze-${Date.now()}.png`;
+      if (!fs.existsSync(config.screenshotsDir)) {
+        fs.mkdirSync(config.screenshotsDir, { recursive: true });
+      }
+      const screenshotPath = path.join(config.screenshotsDir, filename);
+      await page.screenshot({ path: screenshotPath, fullPage: false });
+
+      const cwd = args.cwd || process.cwd();
+      const projectName = config.projectName || path.basename(cwd);
+      const projectId = ensureProject(cwd, projectName, config.screenshotsDir, config.testsDir);
+      const hash = computeScreenshotHash(screenshotPath);
+      registerScreenshotHash(hash, screenshotPath, projectId, null);
+      screenshotHash = `ss:${hash}`;
+      meta.screenshotHash = screenshotHash;
+
+      const data = fs.readFileSync(screenshotPath);
+      screenshotBase64 = data.toString('base64');
+    }
+
+    const result = { meta, ...structure, suggestedTests };
+    const content = [{ type: 'text', text: JSON.stringify(result, null, 2) }];
+
+    if (screenshotBase64) {
+      content.push({ type: 'image', data: screenshotBase64, mimeType: 'image/png' });
+    }
+
+    return { content };
+  } finally {
+    if (browser) browser.disconnect();
+  }
+}
+
+async function handleCapture(args) {
+  if (!args.url) return errorResult('Missing required parameter: url');
+
+  const config = await loadConfig({}, args.cwd);
+  const capturePoolUrls = getPoolUrls(config);
+  const capturePool = await selectPool(capturePoolUrls, 2000, 60000, { poolDriver: config.poolDriver, maxSessions: config.maxSessions });
 
   let browser;
   try {
-    browser = await connectToPool(config.poolUrl);
+    browser = await connectToPool(capturePool);
     const page = await browser.newPage();
     await page.setViewport(config.viewport);
 
-    // Inject auth token into localStorage before navigation
-    const authToken = args.authToken || config.authToken;
+    // Resolve auth token: explicit arg > config static > auto-login
+    const authToken = args.authToken || await resolveAuthToken(config);
     if (authToken) {
       const storageKey = args.authStorageKey || config.authStorageKey || 'accessToken';
       // Navigate to origin first so localStorage is accessible
@@ -854,7 +1991,7 @@ async function handleCapture(args) {
       await page.evaluate((key, token) => { localStorage.setItem(key, token); }, storageKey, authToken);
     }
 
-    await page.goto(args.url, { waitUntil: 'networkidle2', timeout: 30000 });
+    await smartNavigate(page, args.url, args.waitUntil);
 
     if (args.selector) {
       await page.waitForSelector(args.selector, { timeout: 10000 });
@@ -921,6 +2058,35 @@ async function handleDashboardStop() {
   return textResult('Dashboard stopped');
 }
 
+async function handleDashboardRestart(args) {
+  const port = args.port || (dashboardHandle ? dashboardHandle.port : 8484);
+
+  // Stop current instance if we own it
+  if (dashboardHandle) {
+    stopDashboard(dashboardHandle);
+    dashboardHandle = null;
+  }
+
+  // Kill any process occupying the target port (e.g. from another session)
+  try {
+    const { execFileSync } = await import('child_process');
+    const lsof = execFileSync('lsof', ['-ti', `:${port}`], { encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'] }).trim();
+    if (lsof) {
+      for (const pid of lsof.split('\n').filter(Boolean)) {
+        try { process.kill(Number(pid), 'SIGTERM'); } catch {}
+      }
+      // Brief wait for port to free up
+      await new Promise(r => setTimeout(r, 500));
+    }
+  } catch {}
+
+  // Start fresh
+  const overrides = { dashboardPort: port };
+  const config = await loadConfig(overrides, args.cwd);
+  dashboardHandle = await startDashboard(config);
+  return textResult(`Dashboard restarted at http://localhost:${dashboardHandle.port}`);
+}
+
 async function handleNeo4j(args) {
   if (!args.action) return errorResult('Missing required parameter: action');
 
@@ -1012,8 +2178,10 @@ async function handleLearnings(args) {
       return textResult(JSON.stringify(getErrorPatterns(projectId), null, 2));
     case 'trends':
       return textResult(JSON.stringify(getTestTrends(projectId, days), null, 2));
+    case 'actions':
+      return textResult(JSON.stringify(getActionHealthScores(projectId, days), null, 2));
     default:
-      return errorResult(`Unknown query: "${args.query}". Use: summary, flaky, selectors, pages, apis, errors, trends, test:<name>, page:<path>, selector:<value>`);
+      return errorResult(`Unknown query: "${args.query}". Use: summary, flaky, selectors, pages, apis, errors, trends, actions, test:<name>, page:<path>, selector:<value>`);
   }
 }
 
@@ -1039,6 +2207,127 @@ async function handleNetworkLogs(args) {
   return textResult(JSON.stringify(results, null, 2));
 }
 
+async function handleVars(args) {
+  const action = args.action;
+  if (!action) return errorResult('Missing required parameter: action');
+
+  const cwd = args.cwd || process.cwd();
+  const config = await loadConfig({}, cwd);
+  const projectName = config.projectName || cwd.split('/').pop() || 'default';
+  const projectId = ensureProject(cwd, projectName, config.screenshotsDir, config.testsDir);
+  const scope = args.scope || 'project';
+
+  switch (action) {
+    case 'set': {
+      if (!args.key) return errorResult('Missing required parameter: key');
+      if (args.value === undefined) return errorResult('Missing required parameter: value');
+      setVariable(projectId, scope, args.key, args.value);
+      return textResult(`Variable set: ${args.key} (scope: ${scope})`);
+    }
+    case 'get': {
+      if (!args.key) return errorResult('Missing required parameter: key');
+      const vars = getVariables(projectId, scope);
+      if (vars[args.key] !== undefined) {
+        return textResult(JSON.stringify({ key: args.key, value: vars[args.key], scope }));
+      }
+      // Fall back to project scope if not found in specific scope
+      if (scope !== 'project') {
+        const projectVars = getVariables(projectId, 'project');
+        if (projectVars[args.key] !== undefined) {
+          return textResult(JSON.stringify({ key: args.key, value: projectVars[args.key], scope: 'project' }));
+        }
+      }
+      return errorResult(`Variable not found: ${args.key} (scope: ${scope})`);
+    }
+    case 'list': {
+      const all = listVariables(projectId);
+      if (Object.keys(all).length === 0) {
+        return textResult('No variables set for this project.');
+      }
+      return textResult(JSON.stringify(all, null, 2));
+    }
+    case 'delete': {
+      if (!args.key) return errorResult('Missing required parameter: key');
+      const deleted = deleteVariable(projectId, scope, args.key);
+      if (deleted) {
+        return textResult(`Variable deleted: ${args.key} (scope: ${scope})`);
+      }
+      return errorResult(`Variable not found: ${args.key} (scope: ${scope})`);
+    }
+    default:
+      return errorResult(`Unknown action: ${action}. Use set, get, list, or delete.`);
+  }
+}
+
+// ── Verification instructions builder ─────────────────────────────────────────
+
+function buildVerificationInstructions(strictness, hasBaselines, hasChecklists) {
+  const levels = {
+    strict: 'STRICT — No ambiguity allowed. If ANY criterion is unclear, not fully visible, or doubtful, verdict is FAIL. Err on the side of failing.',
+    moderate: 'MODERATE — Use reasonable judgment. Minor cosmetic differences are acceptable, but functional mismatches or missing elements are FAIL.',
+    lenient: 'LENIENT — Only fail on clear, obvious contradictions. Partial matches and minor discrepancies are acceptable.',
+  };
+
+  const lines = [
+    `Verification strictness: ${levels[strictness] || levels.moderate}`,
+    '',
+    'For each entry in the verifications array:',
+    '',
+    '1. RETRIEVE SCREENSHOTS',
+    '   - Call e2e_screenshot with the screenshotHash (after-state).',
+  ];
+
+  if (hasBaselines) {
+    lines.push('   - If baselineScreenshotHash is present, also call e2e_screenshot with it (before-state).');
+  }
+
+  lines.push(
+    '',
+    '2. EVALUATE',
+  );
+
+  if (hasChecklists) {
+    lines.push(
+      '   - If isChecklist is true, evaluate EACH item in the expect array independently as PASS or FAIL.',
+      '   - If isChecklist is false (or absent), evaluate the single expect description as a whole.',
+    );
+  } else {
+    lines.push('   - Compare the screenshot against the expect description.');
+  }
+
+  if (hasBaselines) {
+    lines.push(
+      '',
+      '3. COMPARE BEFORE/AFTER',
+      '   - If a baseline screenshot was retrieved, describe the state change between baseline and after screenshots.',
+      '   - Verify the state change is consistent with what the test actions intended.',
+    );
+  }
+
+  lines.push(
+    '',
+    `${hasBaselines ? '4' : '3'}. REPORT VERDICT — use this exact format for each test:`,
+    '',
+    '   TEST: <test-name>',
+    '   VERDICT: PASS | FAIL',
+  );
+
+  if (hasBaselines) {
+    lines.push('   STATE CHANGE: <one-line description of what changed from baseline to after>');
+  }
+
+  if (hasChecklists) {
+    lines.push(
+      '   CRITERIA:',
+      '     - "<criterion text>": PASS | FAIL (reason if FAIL)',
+    );
+  }
+
+  lines.push('   REASON: <brief explanation of the verdict>');
+
+  return lines.join('\n');
+}
+
 // ── Helpers ───────────────────────────────────────────────────────────────────
 
 export function textResult(text) {
@@ -1062,24 +2351,32 @@ export async function dispatchTool(name, args = {}) {
       return await handleCreateTest(args);
     case 'e2e_pool_status':
       return await handlePoolStatus(args);
+    case 'e2e_app_pool_status':
+      return await handleAppPoolStatus(args);
     case 'e2e_screenshot':
       return await handleScreenshot(args);
     case 'e2e_dashboard_start':
       return await handleDashboardStart(args);
     case 'e2e_dashboard_stop':
       return await handleDashboardStop();
+    case 'e2e_dashboard_restart':
+      return await handleDashboardRestart(args);
     case 'e2e_issue':
       return await handleIssue(args);
     case 'e2e_create_module':
       return await handleCreateModule(args);
     case 'e2e_capture':
       return await handleCapture(args);
+    case 'e2e_analyze':
+      return await handleAnalyze(args);
     case 'e2e_learnings':
       return await handleLearnings(args);
     case 'e2e_neo4j':
       return await handleNeo4j(args);
     case 'e2e_network_logs':
       return await handleNetworkLogs(args);
+    case 'e2e_vars':
+      return await handleVars(args);
     default:
       return errorResult(`Unknown tool: ${name}`);
   }