@matware/e2e-runner 1.3.1 → 1.5.0

package/src/actions.js

@@ -11,6 +11,48 @@ import path from 'path';
 import fs from 'fs';
 import { assertVisualMatch } from './visual-diff.js';
 
+/**
+ * Returns false when the page has nothing useful to capture — used to
+ * skip screenshots that would otherwise be saved as pure-color PNGs
+ * (about:blank, fresh tab before navigation, DOM-only drivers that
+ * never paint, etc). Fails open: on any evaluation error we assume
+ * there *is* content so we don't lose legitimate captures.
+ */
+export async function pageHasRenderableContent(page) {
+  try {
+    const url = page.url();
+    if (!url || url === 'about:blank' || url === 'about:srcdoc') return false;
+    return await page
+      .evaluate(() => {
+        if (!document.body) return false;
+        if (document.body.children.length > 0) return true;
+        return (document.body.innerText || '').trim().length > 0;
+      })
+      .catch(() => true);
+  } catch {
+    return true;
+  }
+}
+
+/**
+ * Heuristic post-capture guard: PNGs compressed under this size at
+ * typical viewport resolutions are almost certainly near-uniform color
+ * (about:blank, default Chrome BG, broken render). Catches cases the
+ * pre-capture DOM check can't — e.g. browserless rendering example.com
+ * to a 99%-gray frame even though navigation succeeded.
+ *
+ * 20 KB sits cleanly between the observed blank cluster (5 KB – 18 KB)
+ * and the smallest real captures in this project (~23 KB+).
+ */
+export const BLANK_PNG_BYTE_THRESHOLD = 20000;
+export const BLANK_JPEG_BYTE_THRESHOLD = 8000;
+
+export function looksLikeBlankCapture(buf, format = 'png') {
+  if (!Buffer.isBuffer(buf)) return false;
+  const threshold = format === 'jpeg' ? BLANK_JPEG_BYTE_THRESHOLD : BLANK_PNG_BYTE_THRESHOLD;
+  return buf.length < threshold;
+}
+
 /** All recognized action types — single source of truth for validation. */
 export const KNOWN_ACTION_TYPES = new Set([
   'goto', 'click', 'type', 'fill', 'wait', 'screenshot',
@@ -20,7 +62,7 @@ export const KNOWN_ACTION_TYPES = new Set([
   'assert_no_network_errors', 'assert_storage',
   'get_text', 'select', 'clear', 'clear_cookies', 'press', 'scroll', 'hover',
   'navigate', 'evaluate',
-  'type_react', 'click_regex', 'click_option', 'focus_autocomplete', 'click_chip',
+  'type_react', 'click_regex', 'click_option', 'select_combobox', 'focus_autocomplete', 'click_chip',
   'set_storage', 'click_icon', 'click_menu_item', 'click_in_context',
   'assert_text_in', 'assert_no_text',
   'gql', 'wait_network_idle',
@@ -50,16 +92,35 @@ export async function executeAction(page, action, config) {
         await page.click(selector);
       } else if (text) {
         const clickTextSelector = 'button, a, [role="button"], [role="tab"], [role="menuitem"], [role="option"], [role="listitem"], div[class*="cursor"], span, li, td, th, label, p, h1, h2, h3, h4, h5, h6, dd, dt';
+        // Optional refinements (backward-compatible — defaults match old behavior):
+        //   scope: "dialog" → only match inside an open [role=dialog]/MuiDialog
+        //   visible: true   → skip hidden/zero-size matches (implied by scope:dialog)
+        //   last: true      → click the LAST match instead of the first
+        const scopeSel = action.scope === 'dialog' ? '[role="dialog"], .MuiDialog-root' : null;
+        const wantVisible = action.visible === true || action.scope === 'dialog';
+        const wantLast = action.last === true;
         await page.waitForFunction(
-          (t, sel) => [...document.querySelectorAll(sel)]
-            .find(el => el.textContent.includes(t)),
+          (t, sel, scope, vis) => {
+            const roots = scope ? [...document.querySelectorAll(scope)] : [document];
+            const isVis = el => { if (!vis) return true; const r = el.getBoundingClientRect(); const s = getComputedStyle(el); return r.width > 0 && r.height > 0 && s.display !== 'none' && s.visibility !== 'hidden'; };
+            for (const root of roots) {
+              if ([...root.querySelectorAll(sel)].some(el => el.textContent.includes(t) && isVis(el))) return true;
+            }
+            return false;
+          },
           { timeout },
-          text, clickTextSelector
+          text, clickTextSelector, scopeSel, wantVisible
         );
-        await page.$$eval(clickTextSelector, (els, t) => {
-          const el = els.find(e => e.textContent.includes(t));
-          if (el) el.click();
-        }, text);
+        const clicked = await page.evaluate((t, sel, scope, vis, last) => {
+          const roots = scope ? [...document.querySelectorAll(scope)] : [document];
+          const isVis = el => { if (!vis) return true; const r = el.getBoundingClientRect(); const s = getComputedStyle(el); return r.width > 0 && r.height > 0 && s.display !== 'none' && s.visibility !== 'hidden'; };
+          const matches = [];
+          for (const root of roots) matches.push(...[...root.querySelectorAll(sel)].filter(el => el.textContent.includes(t) && isVis(el)));
+          const el = last ? matches[matches.length - 1] : matches[0];
+          if (el) { el.click(); return true; }
+          return false;
+        }, text, clickTextSelector, scopeSel, wantVisible, wantLast);
+        if (!clicked) throw new Error(`click failed: no element containing "${text}"${scopeSel ? ' in an open dialog' : ''} found`);
       }
       break;
 
@@ -71,8 +132,34 @@ export async function executeAction(page, action, config) {
       await page.type(selector, value, { delay: 20 });
       break;
 
-    case 'wait':
-      if (selector) {
+    case 'wait': {
+      // Condition waits (preferred over fixed sleeps):
+      //   { selector }            → wait until it appears
+      //   { text }                → wait until text appears in the page
+      //   { gone: "<css>" }       → wait until that selector disappears/hides (e.g. spinner)
+      //   { gone: true, selector }→ same, selector form
+      //   { gone: true, text }    → wait until text disappears
+      //   { value: "<ms>" }       → fixed sleep (last resort)
+      const goneSel = typeof action.gone === 'string' ? action.gone : (action.gone === true ? selector : null);
+      const goneTxt = action.gone === true && !selector ? text : null;
+      if (goneSel) {
+        try {
+          await page.waitForFunction((sel) => {
+            const el = document.querySelector(sel);
+            if (!el) return true;
+            const r = el.getBoundingClientRect(); const s = getComputedStyle(el);
+            return (r.width === 0 && r.height === 0) || s.display === 'none' || s.visibility === 'hidden' || s.opacity === '0';
+          }, { timeout }, goneSel);
+        } catch (e) {
+          throw new Error(`wait failed: "${goneSel}" still present/visible after ${timeout}ms`);
+        }
+      } else if (goneTxt) {
+        try {
+          await page.waitForFunction((t) => !document.body.innerText.includes(t), { timeout }, goneTxt);
+        } catch (e) {
+          throw new Error(`wait failed: text "${goneTxt}" still present after ${timeout}ms`);
+        }
+      } else if (selector) {
         try {
           await page.waitForSelector(selector, { timeout });
         } catch (e) {
@@ -92,6 +179,7 @@ export async function executeAction(page, action, config) {
         await sleep(parseInt(value));
       }
       break;
+    }
 
     case 'screenshot': {
       let filename = value || `screenshot-${Date.now()}.png`;
@@ -108,7 +196,20 @@ export async function executeAction(page, action, config) {
         filename = `${base}-${Date.now()}${ext}`;
       }
       const filepath = path.join(screenshotsDir, filename);
-      await page.screenshot({ path: filepath, fullPage: action.fullPage || false });
+      // Skip capture when page is at about:blank or DOM is empty — these
+      // produce uniform-color PNGs that pollute screenshotsDir with no
+      // diagnostic value.
+      if (!(await pageHasRenderableContent(page))) {
+        return { screenshot: null, skipped: 'blank-page' };
+      }
+      // Capture to buffer first so we can post-filter near-uniform frames
+      // (e.g. browserless returning a 99%-gray render). Only persist if
+      // the encoded PNG carries enough entropy to be informative.
+      const ssBuf = await page.screenshot({ fullPage: action.fullPage || false });
+      if (looksLikeBlankCapture(ssBuf, 'png')) {
+        return { screenshot: null, skipped: 'blank-render', bytes: ssBuf.length };
+      }
+      fs.writeFileSync(filepath, ssBuf);
       return { screenshot: filepath };
     }
 
@@ -356,8 +457,11 @@ export async function executeAction(page, action, config) {
     case 'type_react': {
       // Types into React controlled inputs using the native value setter.
       // This bypasses React's synthetic event system which ignores programmatic .value changes.
+      // Optional: blur (commit on blur for fields that validate then),
+      //           waitAfter (ms to wait after — e.g. for debounced autocomplete dropdowns).
       await page.waitForSelector(selector, { timeout });
-      await page.evaluate((sel, val) => {
+      const trBlur = action.blur === true;
+      await page.evaluate((sel, val, doBlur) => {
         const input = document.querySelector(sel);
         if (!input) throw new Error(`type_react: element "${sel}" not found`);
         const proto = input instanceof HTMLTextAreaElement
@@ -367,11 +471,13 @@ export async function executeAction(page, action, config) {
         if (!descriptor || !descriptor.set) {
           throw new Error(`type_react: element "${sel}" has no writable value property`);
         }
+        input.focus();
         descriptor.set.call(input, val);
         input.dispatchEvent(new Event('input', { bubbles: true }));
         input.dispatchEvent(new Event('change', { bubbles: true }));
-        input.focus();
-      }, selector, value);
+        if (doBlur) input.blur();
+      }, selector, value, trBlur);
+      if (action.waitAfter) await sleep(parseInt(action.waitAfter));
       break;
     }
 
@@ -418,6 +524,56 @@ export async function executeAction(page, action, config) {
       break;
     }
 
+    case 'select_combobox': {
+      // Open a MUI Autocomplete / Select, optionally type to filter, then click the
+      // option matching `text` (case-insensitive substring). Falls back across
+      // [role=option], MuiAutocomplete-option and MuiMenuItem so it works for both
+      // Autocomplete listboxes and Select dropdowns.
+      //   selector: combobox input (default input[role='combobox'])
+      //   text:     option to pick (required)
+      //   filter:   text typed into the input before picking (optional)
+      //   openWait/filterWait: ms tuning for async/debounced option loaders
+      const cbInput = selector || "input[role='combobox']";
+      const cbOption = text || action.option;
+      if (!cbOption) throw new Error("select_combobox requires 'text' (option to pick)");
+      const cbFilter = action.filter || '';
+      const cbOpenWait = action.openWait ? parseInt(action.openWait) : 400;
+      const cbFilterWait = action.filterWait ? parseInt(action.filterWait) : 600;
+      await page.waitForSelector(cbInput, { timeout });
+      await page.evaluate((sel, flt) => {
+        const input = document.querySelector(sel);
+        if (!input) throw new Error(`select_combobox: input "${sel}" not found`);
+        input.focus();
+        if (typeof input.click === 'function') input.click();
+        if (flt) {
+          const proto = input instanceof HTMLTextAreaElement ? HTMLTextAreaElement.prototype : HTMLInputElement.prototype;
+          const setter = Object.getOwnPropertyDescriptor(proto, 'value').set;
+          setter.call(input, flt);
+          input.dispatchEvent(new Event('input', { bubbles: true }));
+          input.dispatchEvent(new Event('change', { bubbles: true }));
+        }
+      }, cbInput, cbFilter);
+      await sleep(cbFilter ? cbFilterWait : cbOpenWait);
+      const cbOptionSel = '[role="option"], .MuiAutocomplete-option, li.MuiMenuItem-root, .MuiList-root li';
+      try {
+        await page.waitForFunction(
+          (sels, t) => [...document.querySelectorAll(sels)].some(o => (o.textContent || '').toLowerCase().includes(t.toLowerCase())),
+          { timeout }, cbOptionSel, cbOption
+        );
+      } catch (e) {
+        throw new Error(`select_combobox: no option matching "${cbOption}" appeared (filter="${cbFilter}")`);
+      }
+      const cbPicked = await page.evaluate((sels, t) => {
+        const c = [...document.querySelectorAll(sels)];
+        const m = c.find(o => (o.textContent || '').toLowerCase().includes(t.toLowerCase()));
+        if (m) { m.click(); return (m.textContent || '').trim().slice(0, 80); }
+        return null;
+      }, cbOptionSel, cbOption);
+      if (cbPicked === null) throw new Error(`select_combobox: option "${cbOption}" vanished before click`);
+      if (action.waitAfter) await sleep(parseInt(action.waitAfter));
+      break;
+    }
+
     case 'focus_autocomplete': {
       // Focus an autocomplete/combobox input by its label text.
       // Supports MUI Autocomplete (.MuiAutocomplete-root) and generic [role="combobox"].

package/src/config.js

@@ -60,6 +60,12 @@ const DEFAULTS = {
   screencastMaxWidth: 800,
   screencastMaxHeight: 600,
   screencastEveryNthFrame: 1,
+  // Auto-capture a thumbnail after each action so the storyline view is fully visual.
+  // Adds ~50-100ms per action; set false in CI if you only need final/error screenshots.
+  autoCaptureSteps: true,
+  autoCaptureWidth: 480,
+  autoCaptureHeight: 300,
+  autoCaptureQuality: 60,
   anthropicApiKey: null,
   anthropicModel: 'claude-sonnet-4-5-20250929',
   authToken: null,

package/src/dashboard.js

@@ -16,12 +16,13 @@ import { createRequire } from 'module';
 import { createWebSocketServer } from './websocket.js';
 import { getPoolUrls, getAggregatedPoolStatus, waitForAnyPool } from './pool-manager.js';
 import { runTestsParallel, loadAllSuites, loadTestSuite, listSuites } from './runner.js';
+import { runModuleAnalysis } from './module-analysis.js';
 import { generateReport, generateJUnitXML, saveReport, persistRun, loadHistory, loadHistoryRun } from './reporter.js';
 import { listProjects as dbListProjects, listProjectsWithSparklines as dbListProjectsWithSparklines, getProjectRuns as dbGetProjectRuns, getRunDetail as dbGetRunDetail, getAllRuns as dbGetAllRuns, getRunCount as dbGetRunCount, getProjectScreenshotsDir as dbGetProjectScreenshotsDir, getProjectTestsDir as dbGetProjectTestsDir, getProjectCwd as dbGetProjectCwd, lookupScreenshotHash as dbLookupScreenshotHash, ensureProject as dbEnsureProject, getNetworkLogs as dbGetNetworkLogs, listVariables as dbListVariables, setVariable as dbSetVariable, deleteVariable as dbDeleteVariable, closeDb } from './db.js';
 import { loadConfig } from './config.js';
 import { log, colors as C } from './logger.js';
 import { getLearningsSummary, getFlakySummary, getSelectorStability, getPageHealth, getApiHealth, getErrorPatterns, getTestTrends, getRunInsights, getHealthSnapshot, getActionHealthScores } from './learner-sqlite.js';
-import { compareImages } from './visual-diff.js';
+import { compareImages, isBlankImage } from './visual-diff.js';
 import { handleSyncRoutes } from './sync/hub-routes.js';
 import { migrateSyncSchema } from './sync/schema.js';
 
@@ -89,11 +90,16 @@ export async function startDashboard(config) {
     const url = new URL(req.url, `http://localhost:${port}`);
     const pathname = url.pathname;
 
-    // CORS — restrict to same-origin (localhost on dashboard port)
+    // CORS — allow same-origin (Origin's host matches the Host header)
+    // and the explicit whitelist (localhost/127.0.0.1 on dashboard port).
     const allowedOrigins = [`http://localhost:${port}`, `http://127.0.0.1:${port}`];
     const origin = req.headers.origin;
-    if (origin && allowedOrigins.includes(origin)) {
-      res.setHeader('Access-Control-Allow-Origin', origin);
+    if (origin) {
+      let allowOrigin = allowedOrigins.includes(origin);
+      if (!allowOrigin && req.headers.host) {
+        try { allowOrigin = new URL(origin).host === req.headers.host; } catch { /* */ }
+      }
+      if (allowOrigin) res.setHeader('Access-Control-Allow-Origin', origin);
     }
     res.setHeader('Access-Control-Allow-Methods', 'GET, POST, PUT, DELETE, OPTIONS');
     res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Accept, Mcp-Session-Id');
@@ -356,6 +362,28 @@ export async function startDashboard(config) {
         return;
       }
 
+      // API: DB — scan a project's screenshots for blank (uniform-color) images
+      const blankScanMatch = pathname.match(/^\/api\/db\/projects\/(\d+)\/screenshots\/blank-scan$/);
+      if (blankScanMatch) {
+        try {
+          const projectId = parseInt(blankScanMatch[1], 10);
+          const dir = dbGetProjectScreenshotsDir(projectId);
+          if (!dir || !fs.existsSync(dir)) { jsonResponse(res, { blanks: [], scanned: 0 }); return; }
+          // Only PNGs are decodable; other formats are skipped (never flagged).
+          const files = fs.readdirSync(dir).filter(f => /\.png$/i.test(f)).sort();
+          const blanks = [];
+          for (const f of files) {
+            const fp = path.join(dir, f);
+            const r = isBlankImage(fp);
+            if (r.blank) blanks.push({ name: f, path: fp, color: r.color, brightness: r.brightness });
+          }
+          jsonResponse(res, { blanks, scanned: files.length });
+        } catch (error) {
+          jsonResponse(res, { error: error.message }, 500);
+        }
+        return;
+      }
+
       // API: DB — project suites list
       const projectSuitesMatch = pathname.match(/^\/api\/db\/projects\/(\d+)\/suites$/);
       if (projectSuitesMatch) {
@@ -458,6 +486,68 @@ export async function startDashboard(config) {
         return;
       }
 
+      // API: Tools — proxy to MCP tool handlers
+      // Generic helper: resolve projectId from POST body → cwd, then call dispatchTool.
+      if (pathname.startsWith('/api/tool/') && req.method === 'POST') {
+        const tool = pathname.replace('/api/tool/', '');
+        const map = { capture: 'e2e_capture', analyze: 'e2e_analyze', 'issue-verify': 'e2e_issue' };
+        const mcpName = map[tool];
+        if (!mcpName) { jsonResponse(res, { error: 'Unknown tool: ' + tool }, 400); return; }
+        let body = '';
+        let oversize = false;
+        req.on('data', chunk => { body += chunk; if (body.length > MAX_BODY) { oversize = true; req.destroy(); } });
+        req.on('end', async () => {
+          if (oversize) { jsonResponse(res, { error: 'Payload too large' }, 413); return; }
+          try {
+            const args = body ? JSON.parse(body) : {};
+            if (args.projectId) {
+              const pcwd = dbGetProjectCwd(parseInt(args.projectId, 10));
+              if (pcwd) args.cwd = pcwd;
+              delete args.projectId;
+            }
+            if (tool === 'issue-verify') args.mode = 'verify';
+            const result = await dispatchTool(mcpName, args);
+            // dispatchTool returns MCP-style { content:[{type,text}], isError? }.
+            // Convert to a friendlier shape for the dashboard.
+            let payload = result;
+            if (result && Array.isArray(result.content)) {
+              const text = result.content.map(c => c.text || '').join('\n');
+              let parsed = null; try { parsed = JSON.parse(text); } catch { /* */ }
+              payload = parsed || { text };
+              if (result.isError) payload.error = payload.error || payload.text || 'Tool returned error';
+            }
+            jsonResponse(res, payload);
+          } catch (error) {
+            jsonResponse(res, { error: error.message }, 500);
+          }
+        });
+        return;
+      }
+
+      // API: Tools — module analysis
+      // Reads all tests + modules in a project, finds repeated 3-8-action
+      // subsequences that appear in 2+ tests (extraction candidates), and
+      // counts current module usage. Returns a report ready for the
+      // dashboard to display + a prompt the user can paste into Claude Code
+      // to ask the test-improver agent for deeper analysis.
+      const modAnalysisMatch = pathname.match(/^\/api\/tools\/module-analysis\/(\d+)$/);
+      if (modAnalysisMatch) {
+        try {
+          const projectId = parseInt(modAnalysisMatch[1], 10);
+          const cwd = dbGetProjectCwd(projectId);
+          const testsDir = dbGetProjectTestsDir(projectId);
+          if (!cwd || !testsDir || !fs.existsSync(testsDir)) {
+            jsonResponse(res, { error: 'Project tests directory not found' }, 404);
+            return;
+          }
+          const modulesDir = path.join(cwd, 'e2e', 'modules');
+          jsonResponse(res, runModuleAnalysis(testsDir, modulesDir, projectId));
+        } catch (error) {
+          jsonResponse(res, { error: error.message }, 500);
+        }
+        return;
+      }
+
       // API: DB — project variables (set/upsert)
       if (projectVarsMatch && req.method === 'PUT') {
         let body = '';
@@ -545,6 +635,47 @@ export async function startDashboard(config) {
         return;
       }
 
+      // API: delete screenshots — { paths: [...] }, each validated against known dirs
+      if (pathname === '/api/screenshots/delete' && req.method === 'POST') {
+        let body = '';
+        let oversize = false;
+        req.on('data', chunk => { body += chunk; if (body.length > MAX_BODY) { oversize = true; req.destroy(); } });
+        req.on('end', () => {
+          if (oversize) { jsonResponse(res, { error: 'Payload too large' }, 413); return; }
+          try {
+            const { paths } = body ? JSON.parse(body) : {};
+            if (!Array.isArray(paths) || !paths.length) { jsonResponse(res, { error: 'Missing paths array' }, 400); return; }
+            // Build the allow-list of directories deletions may touch.
+            const allowedDirs = [path.resolve(config.screenshotsDir)];
+            try {
+              for (const p of dbListProjects()) {
+                const dir = p.screenshots_dir || path.join(p.cwd, 'e2e', 'screenshots');
+                allowedDirs.push(path.resolve(dir));
+              }
+            } catch { /* db may be unavailable */ }
+            let deleted = 0;
+            const failed = [];
+            for (const raw of paths) {
+              try {
+                if (typeof raw !== 'string' || !path.isAbsolute(raw)) { failed.push({ path: raw, error: 'Invalid path' }); continue; }
+                const real = fs.realpathSync(raw);
+                const inAllowed = allowedDirs.some(dir => real.startsWith(dir + path.sep) || real === dir);
+                if (!inAllowed) { failed.push({ path: raw, error: 'Access denied' }); continue; }
+                if (!/\.(png|jpg|jpeg|gif|webp)$/i.test(real)) { failed.push({ path: raw, error: 'Not an image' }); continue; }
+                fs.unlinkSync(real);
+                deleted++;
+              } catch (e) {
+                failed.push({ path: raw, error: e.message });
+              }
+            }
+            jsonResponse(res, { deleted, failed });
+          } catch (error) {
+            jsonResponse(res, { error: error.message }, 500);
+          }
+        });
+        return;
+      }
+
       // API: visual diff — compare two screenshots on demand
       if (pathname === '/api/visual-diff') {
         try {

package/src/db.js

@@ -429,6 +429,8 @@ export function saveRun(projectId, report, runId, suiteName, triggeredBy, poolDr
         narrative: a.narrative || undefined,
         error: a.error || undefined,
         actionRetries: a.actionRetries || undefined,
+        autoScreenshot: a.autoScreenshot || undefined,
+        screenshot: a.result?.screenshot || undefined,
       }));
 
       insertTest.run(
@@ -461,6 +463,15 @@ export function saveRun(projectId, report, runId, suiteName, triggeredBy, poolDr
         const actionIdx = r.actions.indexOf(a);
         insertHash.run(computeScreenshotHash(a.result.screenshot), a.result.screenshot, projectId, runDbId, r.name, actionIdx, null, 'action');
       }
+
+      // Auto-captured per-step thumbnails for the storyline view
+      (r.actions || []).forEach((a, idx) => {
+        if (a.autoScreenshot) {
+          try {
+            insertHash.run(computeScreenshotHash(a.autoScreenshot), a.autoScreenshot, projectId, runDbId, r.name, idx, null, 'step');
+          } catch { /* best effort */ }
+        }
+      });
       if (r.errorScreenshot) {
         insertHash.run(computeScreenshotHash(r.errorScreenshot), r.errorScreenshot, projectId, runDbId, r.name, null, null, 'error');
       }

package/src/mcp-tools.js

@@ -137,6 +137,11 @@ export const TOOLS = [
   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
+  click (in dialog):{ type: "click", text: "Confirm", scope: "dialog", last: true } — only [role=dialog]/MuiDialog; visible:true skips hidden; last:true picks last match
+
+**Selecting from a MUI Autocomplete/Select** — DON'T write evaluate to open+filter+pick:
+  select_combobox: { type: "select_combobox", selector: "input[role='combobox']", filter: "cardio", text: "Cardiología" }
+                   — opens the combobox, types optional filter, clicks the matching option (role=option / MuiAutocomplete-option / MuiMenuItem)
 
 **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
@@ -164,12 +169,13 @@ IMPORTANT field rules:
   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 (gone):     { type: "wait", gone: ".MuiBackdrop-root" }    — wait until a selector disappears/hides (spinner, closing dialog)
+  wait:            { type: "wait", value: "2000" }                — fixed delay (last resort — prefer gone/selector/text)
   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
+  type_react:      { type: "type_react", selector: "#email", value: "a@b.com", waitAfter: "400" } — React controlled inputs; optional blur:true / waitAfter ms
   select:          { type: "select", selector: "select#country", value: "US" }
   clear:           { type: "clear", selector: "#search" }
   press:           { type: "press", value: "Enter" }