@vibecheckai/cli 3.1.0 → 3.1.1

package/bin/runners/reality/engine.js

@@ -1,917 +1,917 @@
-/**
- * Reality Mode Execution Engine
- * Step execution, danger classification, assertions, surface discovery
- */
-
-const fs = require("fs");
-const path = require("path");
-const crypto = require("crypto");
-
-// ============================================================================
-// Utilities
-// ============================================================================
-
-function uuid() {
-  try {
-    return crypto.randomUUID();
-  } catch {
-    return crypto.randomBytes(16).toString("hex");
-  }
-}
-
-function randomEmail() {
-  return `reality+${Date.now()}_${Math.floor(Math.random() * 1e6)}@example.com`;
-}
-
-function template(str, vars) {
-  if (typeof str !== "string") return str;
-  return str.replace(/\{\{([^}]+)\}\}/g, (_, key) => {
-    const k = String(key || "").trim();
-    if (k === "$timestamp") return String(Date.now());
-    if (k === "$uuid") return uuid();
-    if (k === "$randomEmail") return randomEmail();
-    if (k === "$isoDate") return new Date().toISOString();
-    if (k.startsWith("env.")) return process.env[k.slice(4)] || "";
-    if (k.startsWith("stored.")) return vars?.[k] ?? "";
-    return vars?.[k] != null ? String(vars[k]) : "";
-  });
-}
-
-// ============================================================================
-// Danger Classification System
-// ============================================================================
-
-const DANGER_TEXT_PATTERNS = [
-  /\bdelete\b/i,
-  /\bremove\b/i,
-  /\bdestroy\b/i,
-  /\bdeactivate\b/i,
-  /\bterminate\b/i,
-  /\bclose\s*account\b/i,
-  /\bcancel\s*subscription\b/i,
-  /\breset\s*all\b/i,
-  /\bwipe\b/i,
-  /\berase\b/i,
-  /\birreversible\b/i,
-  /\bpermanently\b/i,
-  /\bcannot\s*be\s*undone\b/i,
-  /\brevoke\b/i,
-  /\bdisconnect\b/i,
-  /\bunlink\b/i,
-];
-
-const DANGER_CLASS_PATTERNS = [
-  /\bbtn-danger\b/,
-  /\bdestructive\b/,
-  /\bdelete-/,
-  /\bdanger-/,
-  /\bremove-/,
-];
-
-function classifyDanger({ text, className, ariaLabel, role, url, method }) {
-  const signals = [];
-  let score = 0;
-
-  const t = `${text || ""}`.toLowerCase();
-  const cls = `${className || ""}`.toLowerCase();
-  const aria = `${ariaLabel || ""}`.toLowerCase();
-  const r = `${role || ""}`.toLowerCase();
-  const u = `${url || ""}`.toLowerCase();
-  const m = `${method || ""}`.toUpperCase();
-
-  // Text patterns
-  for (const pattern of DANGER_TEXT_PATTERNS) {
-    if (pattern.test(t) || pattern.test(aria)) {
-      signals.push({ type: "text", value: pattern.source, weight: 0.3 });
-      score += 0.3;
-    }
-  }
-
-  // Class patterns
-  for (const pattern of DANGER_CLASS_PATTERNS) {
-    if (pattern.test(cls)) {
-      signals.push({ type: "class", value: pattern.source, weight: 0.25 });
-      score += 0.25;
-    }
-  }
-
-  // ARIA patterns
-  if (r === "alertdialog") {
-    signals.push({ type: "aria", value: "role=alertdialog", weight: 0.2 });
-    score += 0.2;
-  }
-
-  // Network patterns (DELETE method or destructive endpoints)
-  if (m === "DELETE") {
-    signals.push({ type: "network", value: "DELETE method", weight: 0.4 });
-    score += 0.4;
-  }
-  if (/\/delete\b|\/destroy\b|\/deactivate\b|\/remove\b/.test(u)) {
-    signals.push({ type: "network", value: "destructive endpoint", weight: 0.35 });
-    score += 0.35;
-  }
-
-  const dangerous = score >= 0.25;
-  const reason = signals.length > 0 ? signals[0].type : "none";
-
-  return {
-    dangerous,
-    score: Math.min(1, score),
-    signals,
-    reason,
-  };
-}
-
-// ============================================================================
-// Screenshots & DOM Snapshots
-// ============================================================================
-
-async function screenshot(page, outPath) {
-  try {
-    await page.screenshot({ path: outPath, fullPage: true });
-  } catch {
-    // Non-fatal
-  }
-}
-
-async function domSnapshot(page) {
-  try {
-    return await page.evaluate(() => {
-      const el = document.activeElement;
-      return {
-        url: location.href,
-        title: document.title,
-        active: el ? { tag: el.tagName, id: el.id, name: el.getAttribute("name") } : null,
-        bodyTextSample: document.body?.innerText?.slice(0, 500) || "",
-      };
-    });
-  } catch {
-    return null;
-  }
-}
-
-// ============================================================================
-// Navigation Helpers
-// ============================================================================
-
-async function safeGoto(page, url, timeout) {
-  const started = Date.now();
-  try {
-    const res = await page.goto(url, { waitUntil: "domcontentloaded", timeout });
-    await page.waitForLoadState("networkidle", { timeout: Math.min(timeout, 5000) }).catch(() => {});
-    const status = res ? res.status() : 0;
-    return { ok: status >= 200 && status < 400, status, ms: Date.now() - started };
-  } catch (e) {
-    return { ok: false, status: 0, ms: Date.now() - started, error: String(e?.message || e).slice(0, 180) };
-  }
-}
-
-async function findLocator(page, target) {
-  return page.locator(target).first();
-}
-
-// ============================================================================
-// Surface Discovery
-// ============================================================================
-
-async function discoverSurface({ page, baseUrl, timeout, maxPages }) {
-  const discovered = {
-    routes: [],
-    elements: [],
-    forms: [],
-  };
-
-  // Visit base
-  const home = await safeGoto(page, baseUrl, timeout);
-  if (home.status) {
-    discovered.routes.push({ path: "/", status: home.ok ? "success" : "error", httpStatus: home.status });
-  }
-
-  // Extract routes
-  const routes = await page.evaluate(() => {
-    const out = new Set();
-    document.querySelectorAll("a[href]").forEach(a => {
-      const href = a.getAttribute("href") || "";
-      if (!href || href.startsWith("http") || href.startsWith("//") || href.includes("#")) return;
-      if (href.startsWith("/")) out.add(href);
-    });
-    // Common SPA routes
-    ["/dashboard", "/app", "/account", "/settings", "/profile", "/projects", "/analytics", "/billing"].forEach(r => out.add(r));
-    return Array.from(out);
-  }).catch(() => []);
-
-  const queue = routes.slice(0, maxPages * 2);
-  const seen = new Set(["/", baseUrl]);
-
-  for (const route of queue.slice(0, maxPages)) {
-    if (seen.has(route)) continue;
-    seen.add(route);
-
-    const res = await safeGoto(page, baseUrl + route, timeout);
-    discovered.routes.push({
-      path: route,
-      status: res.ok ? "success" : "error",
-      httpStatus: res.status || 0,
-      error: res.error,
-    });
-
-    // Discover elements on this page
-    const pageEls = await page.evaluate(() => {
-      const pickText = (el) => (el.textContent || el.getAttribute("aria-label") || "").trim().slice(0, 80);
-      const els = Array.from(document.querySelectorAll('button, [role="button"], input[type="submit"], a[href], [data-testid]'));
-      return els.slice(0, 100).map((el, idx) => ({
-        tag: el.tagName.toLowerCase(),
-        text: pickText(el),
-        id: el.id || "",
-        testid: el.getAttribute("data-testid") || "",
-        className: el.className || "",
-        ariaLabel: el.getAttribute("aria-label") || "",
-        href: el.getAttribute("href") || "",
-        index: idx,
-      }));
-    }).catch(() => []);
-
-    for (const e of pageEls) {
-      if (!e.text && !e.testid && !e.id) continue;
-      discovered.elements.push({ ...e, page: route });
-    }
-
-    // Discover forms
-    const forms = await page.evaluate(() => {
-      const forms = Array.from(document.querySelectorAll("form"));
-      return forms.slice(0, 20).map((form, idx) => {
-        const fields = Array.from(form.querySelectorAll("input, textarea, select")).slice(0, 30).map((f) => ({
-          name: f.getAttribute("name") || f.id || "",
-          type: f.getAttribute("type") || f.tagName.toLowerCase(),
-          required: !!f.required,
-        }));
-        return {
-          selector: form.id ? `#${form.id}` : form.getAttribute("data-testid") ? `[data-testid="${form.getAttribute("data-testid")}"]` : `form:nth-of-type(${idx + 1})`,
-          fields,
-        };
-      });
-    }).catch(() => []);
-
-    for (const f of forms) discovered.forms.push({ ...f, page: route });
-  }
-
-  // Dedupe
-  discovered.routes = dedupe(discovered.routes, r => r.path);
-  discovered.elements = dedupe(discovered.elements, e => `${e.page}|${e.tag}|${e.testid}|${e.id}|${e.text}`);
-  discovered.forms = dedupe(discovered.forms, f => `${f.page}|${f.selector}`);
-
-  return discovered;
-}
-
-function dedupe(arr, keyFn) {
-  const seen = new Set();
-  const out = [];
-  for (const x of arr) {
-    const k = keyFn(x);
-    if (seen.has(k)) continue;
-    seen.add(k);
-    out.push(x);
-  }
-  return out;
-}
-
-// ============================================================================
-// Flow Plan Execution
-// ============================================================================
-
-async function runFlowPlan({ plan, page, context, telemetry }) {
-  const results = {
-    meta: {
-      baseUrl: plan.baseUrl,
-      startedAt: new Date().toISOString(),
-      danger: plan.danger,
-      maxPages: plan.maxPages,
-      timeout: plan.timeout,
-    },
-    discovery: null,
-    coverage: {
-      routesDiscovered: 0,
-      routesWorking: 0,
-      elementsDiscovered: 0,
-      elementsWorking: 0,
-      formsDiscovered: 0,
-      formsWorking: 0,
-    },
-    flows: [],
-    routes: [],
-    elements: [],
-    forms: [],
-    errors: [],
-    network: [],
-    console: [],
-    timeline: [],
-    score: 0,
-    duration: 0,
-  };
-
-  // Discovery pass
-  const discovery = await discoverSurface({
-    page,
-    baseUrl: plan.baseUrl,
-    timeout: plan.timeout,
-    maxPages: plan.maxPages,
-  });
-
-  results.discovery = {
-    routes: discovery.routes.length,
-    elements: discovery.elements.length,
-    forms: discovery.forms.length,
-  };
-
-  results.routes = discovery.routes;
-  results.elements = discovery.elements;
-  results.forms = discovery.forms;
-
-  results.coverage.routesDiscovered = discovery.routes.length;
-  results.coverage.routesWorking = discovery.routes.filter(r => r.status === "success").length;
-  results.coverage.elementsDiscovered = discovery.elements.length;
-  results.coverage.formsDiscovered = discovery.forms.length;
-
-  // Collect telemetry
-  results.console = telemetry.console.slice(-500);
-  results.errors = [
-    ...telemetry.pageErrors.map(e => ({ type: "uncaught", message: e.message, url: e.url, ts: e.ts })),
-    ...telemetry.console.filter(m => m.type === "error").map(m => ({ type: "console", message: m.text, url: m.url, ts: m.ts })),
-  ];
-  results.network = telemetry.responses.slice(-500);
-
-  // Run Flow Packs
-  const flowVarsBase = makeBaseVars(plan);
-  const flowsToRun = Array.isArray(plan.flows) ? plan.flows : [];
-
-  for (const flow of flowsToRun) {
-    const flowResult = await runSingleFlow({
-      flow,
-      plan,
-      page,
-      context,
-      telemetry,
-      varsBase: flowVarsBase,
-      results,
-    });
-    results.flows.push(flowResult);
-  }
-
-  // Count working elements from successful flow steps
-  let elementWorking = 0;
-  for (const f of results.flows) {
-    for (const s of (f.steps || [])) {
-      if ((s.action === "click" || s.action === "fill") && s.status === "success") elementWorking++;
-    }
-  }
-  results.coverage.elementsWorking = Math.min(elementWorking, results.coverage.elementsDiscovered);
-
-  // Calculate score
-  results.score = calculateScore(results);
-
-  return results;
-}
-
-function makeBaseVars(plan) {
-  const vars = {
-    baseUrl: plan.baseUrl,
-    timestamp: String(Date.now()),
-    $timestamp: String(Date.now()),
-    $uuid: uuid(),
-    $randomEmail: randomEmail(),
-    $isoDate: new Date().toISOString(),
-  };
-
-  if (plan.auth && typeof plan.auth === "string" && plan.auth.includes(":")) {
-    const [email, ...rest] = plan.auth.split(":");
-    vars.email = email;
-    vars.password = rest.join(":");
-  }
-
-  return vars;
-}
-
-// ============================================================================
-// Single Flow Execution
-// ============================================================================
-
-async function runSingleFlow({ flow, plan, page, telemetry, varsBase, results }) {
-  const flowStart = Date.now();
-  const flowVars = { ...varsBase, ...(flow.vars || {}) };
-
-  // Template all vars
-  for (const k of Object.keys(flowVars)) {
-    flowVars[k] = template(flowVars[k], flowVars);
-  }
-
-  const flowOut = {
-    id: flow.id,
-    name: flow.name,
-    source: flow.__source,
-    required: !!flow.required,
-    status: "success",
-    startedAt: new Date(flowStart).toISOString(),
-    durationMs: 0,
-    steps: [],
-    assertions: [],
-    errors: [],
-  };
-
-  // Run steps
-  let stepIndex = 0;
-  for (const step of flow.steps || []) {
-    stepIndex++;
-    const stepId = `${flow.id}#${stepIndex}`;
-    const stepName = step.name || `${step.action || "step"}-${stepIndex}`;
-    const stepStart = Date.now();
-
-    const stepRec = {
-      id: stepId,
-      name: stepName,
-      action: step.action,
-      target: step.target || null,
-      status: "success",
-      error: null,
-      danger: null,
-      artifacts: {},
-      startedAt: new Date(stepStart).toISOString(),
-      durationMs: 0,
-    };
-
-    // Trace marker
-    try {
-      await page.evaluate((label) => console.log(`[reality:trace] ${label}`), `STEP ${stepId}`);
-    } catch {}
-
-    // Before screenshot
-    const beforeShot = path.join(plan.artifacts.screenshotsDir, `${flow.id}__${stepIndex}__before.png`);
-    await screenshot(page, beforeShot);
-    stepRec.artifacts.beforeScreenshot = path.relative(plan.outputDir, beforeShot);
-    stepRec.artifacts.beforeDom = await domSnapshot(page);
-
-    // Execute action
-    try {
-      await executeStep({ step, stepRec, plan, page, flowVars, telemetry });
-    } catch (e) {
-      stepRec.status = "error";
-      stepRec.error = String(e?.message || e).slice(0, 220);
-      flowOut.errors.push({ step: stepIndex, message: stepRec.error });
-    }
-
-    // After screenshot
-    const afterShot = path.join(plan.artifacts.screenshotsDir, `${flow.id}__${stepIndex}__after.png`);
-    await screenshot(page, afterShot);
-    stepRec.artifacts.afterScreenshot = path.relative(plan.outputDir, afterShot);
-    stepRec.artifacts.afterDom = await domSnapshot(page);
-
-    stepRec.durationMs = Date.now() - stepStart;
-
-    // Add to timeline
-    results.timeline.push({
-      flowId: flow.id,
-      step: stepIndex,
-      name: stepRec.name,
-      action: stepRec.action,
-      status: stepRec.status,
-      at: Date.now(),
-      url: page.url(),
-      before: stepRec.artifacts.beforeScreenshot,
-      after: stepRec.artifacts.afterScreenshot,
-    });
-
-    flowOut.steps.push(stepRec);
-  }
-
-  // Run assertions
-  for (const a of flow.assertions || []) {
-    const ar = await runAssertion({ assertion: a, plan, page, telemetry, vars: flowVars });
-    flowOut.assertions.push(ar);
-    if (ar.status === "fail" && a.critical) {
-      flowOut.status = "error";
-    }
-  }
-
-  // Cleanup (best-effort)
-  for (const step of flow.cleanup || []) {
-    try {
-      await executeStep({ step, stepRec: {}, plan, page, flowVars, telemetry });
-    } catch {}
-  }
-
-  flowOut.durationMs = Date.now() - flowStart;
-  if (flowOut.errors.length > 0) flowOut.status = "error";
-
-  return flowOut;
-}
-
-// ============================================================================
-// Step Execution
-// ============================================================================
-
-async function executeStep({ step, stepRec, plan, page, flowVars, telemetry }) {
-  const action = String(step.action || "").toLowerCase();
-
-  if (action === "navigate") {
-    const target = template(step.target || "/", flowVars);
-    const url = target.startsWith("http") ? target : (plan.baseUrl + (target.startsWith("/") ? target : `/${target}`));
-    const res = await safeGoto(page, url, plan.timeout);
-    if (!res.ok) throw new Error(res.error || `Navigation failed: ${url}`);
-  }
-
-  else if (action === "wait") {
-    if (step.for === "selector" && step.target) {
-      const target = template(step.target, flowVars);
-      const state = step.state || "visible";
-      const loc = await findLocator(page, target);
-      await loc.waitFor({ state, timeout: Number(step.timeout || plan.timeout) });
-    } else if (step.for === "navigation" && step.match) {
-      const match = new RegExp(template(step.match, flowVars));
-      const timeout = Number(step.timeout || plan.timeout);
-      const end = Date.now() + timeout;
-      while (Date.now() < end) {
-        if (match.test(page.url())) break;
-        await page.waitForTimeout(200);
-      }
-      if (!match.test(page.url())) throw new Error(`URL did not match ${step.match}`);
-    } else if (step.for === "network" && step.match) {
-      const match = template(step.match, flowVars);
-      const timeout = Number(step.timeout || plan.timeout);
-      const since = Date.now();
-      const end = since + timeout;
-      let found = false;
-      while (Date.now() < end) {
-        const recent = telemetry.responses.filter(r => r.ts >= since);
-        if (recent.some(r => r.url.includes(match))) { found = true; break; }
-        await page.waitForTimeout(200);
-      }
-      if (!found) throw new Error(`No network call matching ${match}`);
-    } else {
-      const ms = Number(step.timeout || step.ms || 1000);
-      await page.waitForTimeout(ms);
-    }
-  }
-
-  else if (action === "fill") {
-    const target = template(step.target, flowVars);
-    const value = template(step.value, flowVars);
-    const loc = await findLocator(page, target);
-    await loc.waitFor({ state: "visible", timeout: plan.timeout }).catch(() => {});
-    if (step.clear !== false) await loc.clear().catch(() => {});
-    await loc.fill(String(value ?? ""), { timeout: plan.timeout });
-  }
-
-  else if (action === "click") {
-    const target = template(step.target, flowVars);
-    const loc = await findLocator(page, target);
-
-    // Danger detection
-    let meta = {};
-    try {
-      meta = await loc.evaluate((el) => ({
-        text: (el.textContent || "").trim().slice(0, 120),
-        className: el.className || "",
-        ariaLabel: el.getAttribute("aria-label") || "",
-        role: el.getAttribute("role") || "",
-      }));
-    } catch {}
-
-    const danger = classifyDanger({ ...meta, url: page.url() });
-    stepRec.danger = danger;
-
-    const policy = String(step.dangerPolicy || "skip").toLowerCase();
-    if (danger.dangerous && !plan.danger) {
-      if (policy === "block") {
-        stepRec.status = "blocked";
-        stepRec.error = `Blocked destructive action (${danger.reason}). Use --danger to allow.`;
-        return;
-      }
-      stepRec.status = "skipped";
-      stepRec.error = `Skipped destructive action (${danger.reason}). Use --danger to allow.`;
-      return;
-    }
-
-    await loc.waitFor({ state: "visible", timeout: plan.timeout }).catch(() => {});
-    try {
-      await loc.click({ timeout: plan.timeout });
-    } catch {
-      await loc.click({ timeout: plan.timeout, force: true });
-    }
-    await page.waitForTimeout(300);
-  }
-
-  else if (action === "check") {
-    const target = template(step.target, flowVars);
-    const loc = await findLocator(page, target);
-    await loc.check({ timeout: plan.timeout });
-  }
-
-  else if (action === "uncheck") {
-    const target = template(step.target, flowVars);
-    const loc = await findLocator(page, target);
-    await loc.uncheck({ timeout: plan.timeout });
-  }
-
-  else if (action === "select") {
-    const target = template(step.target, flowVars);
-    const loc = await findLocator(page, target);
-    if (step.value) {
-      await loc.selectOption({ value: template(step.value, flowVars) });
-    } else if (step.label) {
-      await loc.selectOption({ label: template(step.label, flowVars) });
-    } else if (step.index != null) {
-      await loc.selectOption({ index: Number(step.index) });
-    }
-  }
-
-  else if (action === "hover") {
-    const target = template(step.target, flowVars);
-    const loc = await findLocator(page, target);
-    await loc.hover({ timeout: plan.timeout });
-  }
-
-  else if (action === "press") {
-    const key = template(step.key, flowVars);
-    await page.keyboard.press(key);
-  }
-
-  else if (action === "screenshot") {
-    const name = template(step.name || `manual-${Date.now()}`, flowVars);
-    const outPath = path.join(plan.artifacts.screenshotsDir, `${name}.png`);
-    await screenshot(page, outPath);
-    stepRec.artifacts.manualScreenshot = path.relative(plan.outputDir, outPath);
-  }
-
-  else if (action === "scroll") {
-    if (step.to === "bottom") {
-      await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
-    } else if (step.to === "top") {
-      await page.evaluate(() => window.scrollTo(0, 0));
-    } else if (step.target) {
-      const target = template(step.target, flowVars);
-      const loc = await findLocator(page, target);
-      await loc.scrollIntoViewIfNeeded();
-    }
-  }
-
-  else if (action === "execute") {
-    if (step.script) {
-      await page.evaluate(step.script);
-    } else if (step.scriptFile) {
-      const scriptPath = path.resolve(step.scriptFile);
-      const script = fs.readFileSync(scriptPath, "utf8");
-      await page.evaluate(script);
-    }
-  }
-
-  else {
-    stepRec.status = "unknown";
-    stepRec.error = `Unknown action: ${step.action}`;
-  }
-}
-
-// ============================================================================
-// Assertions
-// ============================================================================
-
-async function runAssertion({ assertion, plan, page, telemetry, vars }) {
-  const type = String(assertion.type || "").toLowerCase().replace(/-/g, "");
-  const critical = !!assertion.critical;
-
-  const out = {
-    type: assertion.type,
-    critical,
-    status: "pass",
-    message: "",
-  };
-
-  try {
-    if (type === "urlcontains") {
-      const v = template(assertion.value, vars);
-      if (!page.url().toLowerCase().includes(v.toLowerCase())) {
-        throw new Error(`URL does not contain: ${v} (got ${page.url()})`);
-      }
-    }
-
-    else if (type === "urlmatches") {
-      const v = template(assertion.pattern || assertion.value, vars);
-      const re = new RegExp(v);
-      if (!re.test(page.url())) throw new Error(`URL does not match: ${v}`);
-    }
-
-    else if (type === "urlnotcontains") {
-      const v = template(assertion.value, vars);
-      if (page.url().toLowerCase().includes(v.toLowerCase())) {
-        throw new Error(`URL should not contain: ${v}`);
-      }
-    }
-
-    else if (type === "routechanged") {
-      const within = Number(assertion.within || 3000);
-      const match = assertion.match ? new RegExp(template(assertion.match, vars)) : null;
-      const before = page.url();
-      await page.waitForTimeout(Math.min(within, 500));
-      const after = page.url();
-      if (after === before) throw new Error(`Route did not change`);
-      if (match && !match.test(after)) throw new Error(`Route changed but does not match: ${assertion.match}`);
-    }
-
-    else if (type === "elementvisible") {
-      const target = template(assertion.target, vars);
-      const loc = await findLocator(page, target);
-      await loc.waitFor({ state: "visible", timeout: Number(assertion.within || plan.timeout) });
-    }
-
-    else if (type === "elementhidden") {
-      const target = template(assertion.target, vars);
-      const loc = await findLocator(page, target);
-      await loc.waitFor({ state: "hidden", timeout: Number(assertion.within || plan.timeout) });
-    }
-
-    else if (type === "elementtext") {
-      const target = template(assertion.target, vars);
-      const loc = await findLocator(page, target);
-      const text = await loc.textContent({ timeout: plan.timeout });
-      if (assertion.contains) {
-        const expected = template(assertion.contains, vars);
-        if (!String(text || "").includes(expected)) {
-          throw new Error(`Element text does not contain "${expected}"`);
-        }
-      }
-      if (assertion.matches) {
-        const re = new RegExp(template(assertion.matches, vars));
-        if (!re.test(text || "")) {
-          throw new Error(`Element text does not match ${assertion.matches}`);
-        }
-      }
-    }
-
-    else if (type === "elementcount") {
-      const target = template(assertion.target, vars);
-      const count = await page.locator(target).count();
-      if (assertion.min != null && count < assertion.min) {
-        throw new Error(`Element count ${count} < min ${assertion.min}`);
-      }
-      if (assertion.max != null && count > assertion.max) {
-        throw new Error(`Element count ${count} > max ${assertion.max}`);
-      }
-      if (assertion.equals != null && count !== assertion.equals) {
-        throw new Error(`Element count ${count} !== ${assertion.equals}`);
-      }
-    }
-
-    else if (type === "toastcontains" || type === "notificationvisible") {
-      const v = template(assertion.text || assertion.contains || assertion.value, vars);
-      const within = Number(assertion.within || 5000);
-      const toastSel = assertion.target || '[role="status"], [role="alert"], .toast, .sonner-toast, [data-sonner-toast], .notification';
-      const loc = page.locator(toastSel).filter({ hasText: new RegExp(v, "i") }).first();
-      await loc.waitFor({ state: "visible", timeout: within });
-    }
-
-    else if (type === "toastnotcontains") {
-      const v = template(assertion.text || assertion.value, vars);
-      const within = Number(assertion.within || 3000);
-      const toastSel = assertion.target || '[role="status"], [role="alert"], .toast, .sonner-toast, [data-sonner-toast], .notification';
-      await page.waitForTimeout(Math.min(within, 1500));
-      const count = await page.locator(toastSel).filter({ hasText: new RegExp(v, "i") }).count();
-      if (count > 0) throw new Error(`Toast contains forbidden text: ${v}`);
-    }
-
-    else if (type === "networkcalled") {
-      const v = template(assertion.match || assertion.value, vars);
-      const within = Number(assertion.within || 10000);
-      const minTimes = assertion.times ?? assertion.minTimes ?? 1;
-      const since = Date.now() - within;
-      const matches = telemetry.responses.filter(r => r.ts >= since && r.url.includes(v));
-      if (matches.length < minTimes) {
-        throw new Error(`Expected ${minTimes} calls matching ${v}, got ${matches.length}`);
-      }
-    }
-
-    else if (type === "networkstatus") {
-      const v = template(assertion.match || assertion.value, vars);
-      const expectStatus = Number(assertion.status || 200);
-      const within = Number(assertion.within || 10000);
-      const since = Date.now() - within;
-      const match = telemetry.responses.find(r => r.ts >= since && r.url.includes(v));
-      if (!match) throw new Error(`No response matching: ${v}`);
-      if (match.status !== expectStatus) {
-        throw new Error(`Expected ${expectStatus}, got ${match.status} for ${match.url}`);
-      }
-    }
-
-    else if (type === "networktiming") {
-      const v = template(assertion.match || assertion.value, vars);
-      const maxDuration = Number(assertion.maxDuration || 5000);
-      // Check request/response pairs - simplified version
-      const match = telemetry.responses.find(r => r.url.includes(v));
-      if (!match) throw new Error(`No response matching: ${v}`);
-      // We don't have timing data in this simplified version
-      out.message = `Network timing check (simplified): ${v}`;
-    }
-
-    else if (type === "noconsoleerrors") {
-      const severity = String(assertion.severity || "error").toLowerCase();
-      const windowMs = Number(assertion.within || 60000);
-      const since = Date.now() - windowMs;
-
-      const ignorePatterns = (assertion.ignore || []).map(p => new RegExp(p));
-      
-      const bad = telemetry.console
-        .filter(m => m.ts >= since)
-        .filter(m => {
-          if (severity === "error") return m.type === "error";
-          if (severity === "warning" || severity === "warn") return m.type === "error" || m.type === "warning";
-          return m.type === "error";
-        })
-        .filter(m => !ignorePatterns.some(re => re.test(m.text)));
-
-      if (bad.length > 0) {
-        throw new Error(`Console ${bad[0].type}: ${String(bad[0].text || "").slice(0, 140)}`);
-      }
-    }
-
-    else if (type === "consolecontains") {
-      const match = template(assertion.match || assertion.value, vars);
-      const severity = String(assertion.severity || "log").toLowerCase();
-      const found = telemetry.console.some(m => {
-        if (severity !== "all" && m.type !== severity) return false;
-        return m.text.includes(match);
-      });
-      if (!found) throw new Error(`Console does not contain: ${match}`);
-    }
-
-    else if (type === "localstorage") {
-      const key = template(assertion.key, vars);
-      const value = await page.evaluate((k) => localStorage.getItem(k), key);
-      if (assertion.exists === true && value === null) {
-        throw new Error(`localStorage key "${key}" does not exist`);
-      }
-      if (assertion.exists === false && value !== null) {
-        throw new Error(`localStorage key "${key}" should not exist`);
-      }
-      if (assertion.equals != null && value !== assertion.equals) {
-        throw new Error(`localStorage "${key}" !== "${assertion.equals}"`);
-      }
-      if (assertion.matches) {
-        const re = new RegExp(assertion.matches);
-        if (!re.test(value || "")) throw new Error(`localStorage "${key}" does not match ${assertion.matches}`);
-      }
-    }
-
-    else if (type === "sessionstorage") {
-      const key = template(assertion.key, vars);
-      const value = await page.evaluate((k) => sessionStorage.getItem(k), key);
-      if (assertion.exists === true && value === null) {
-        throw new Error(`sessionStorage key "${key}" does not exist`);
-      }
-      if (assertion.matches) {
-        const re = new RegExp(assertion.matches);
-        if (!re.test(value || "")) throw new Error(`sessionStorage "${key}" does not match ${assertion.matches}`);
-      }
-    }
-
-    else {
-      out.status = "skip";
-      out.message = `Assertion type not implemented: ${assertion.type}`;
-    }
-  } catch (e) {
-    out.status = "fail";
-    out.message = String(e?.message || e).slice(0, 220);
-  }
-
-  return out;
-}
-
-// ============================================================================
-// Score Calculation
-// ============================================================================
-
-function calculateScore(results) {
-  const routesDiscovered = results.coverage?.routesDiscovered || 0;
-  const routesWorking = results.coverage?.routesWorking || 0;
-  const routePct = routesDiscovered ? (routesWorking / routesDiscovered) : 1;
-
-  const flows = results.flows || [];
-  const flowTotal = flows.length || 1;
-  const flowOk = flows.filter(f => f.status === "success").length;
-
-  let assertsTotal = 0;
-  let assertsPass = 0;
-  for (const f of flows) {
-    for (const a of (f.assertions || [])) {
-      if (a.status === "skip") continue;
-      assertsTotal++;
-      if (a.status === "pass") assertsPass++;
-    }
-  }
-  const assertPct = assertsTotal ? (assertsPass / assertsTotal) : 1;
-
-  const errors = results.errors?.length || 0;
-  const penalty = Math.min(errors * 3, 20);
-
-  const score = (routePct * 30) + ((flowOk / flowTotal) * 40) + (assertPct * 30) - penalty;
-
-  return Math.max(0, Math.min(100, Math.round(score)));
-}
-
-module.exports = { runFlowPlan, classifyDanger, discoverSurface };
+/**
+ * Reality Mode Execution Engine
+ * Step execution, danger classification, assertions, surface discovery
+ */
+
+const fs = require("fs");
+const path = require("path");
+const crypto = require("crypto");
+
+// ============================================================================
+// Utilities
+// ============================================================================
+
+function uuid() {
+  try {
+    return crypto.randomUUID();
+  } catch {
+    return crypto.randomBytes(16).toString("hex");
+  }
+}
+
+function randomEmail() {
+  return `reality+${Date.now()}_${Math.floor(Math.random() * 1e6)}@example.com`;
+}
+
+function template(str, vars) {
+  if (typeof str !== "string") return str;
+  return str.replace(/\{\{([^}]+)\}\}/g, (_, key) => {
+    const k = String(key || "").trim();
+    if (k === "$timestamp") return String(Date.now());
+    if (k === "$uuid") return uuid();
+    if (k === "$randomEmail") return randomEmail();
+    if (k === "$isoDate") return new Date().toISOString();
+    if (k.startsWith("env.")) return process.env[k.slice(4)] || "";
+    if (k.startsWith("stored.")) return vars?.[k] ?? "";
+    return vars?.[k] != null ? String(vars[k]) : "";
+  });
+}
+
+// ============================================================================
+// Danger Classification System
+// ============================================================================
+
+const DANGER_TEXT_PATTERNS = [
+  /\bdelete\b/i,
+  /\bremove\b/i,
+  /\bdestroy\b/i,
+  /\bdeactivate\b/i,
+  /\bterminate\b/i,
+  /\bclose\s*account\b/i,
+  /\bcancel\s*subscription\b/i,
+  /\breset\s*all\b/i,
+  /\bwipe\b/i,
+  /\berase\b/i,
+  /\birreversible\b/i,
+  /\bpermanently\b/i,
+  /\bcannot\s*be\s*undone\b/i,
+  /\brevoke\b/i,
+  /\bdisconnect\b/i,
+  /\bunlink\b/i,
+];
+
+const DANGER_CLASS_PATTERNS = [
+  /\bbtn-danger\b/,
+  /\bdestructive\b/,
+  /\bdelete-/,
+  /\bdanger-/,
+  /\bremove-/,
+];
+
+function classifyDanger({ text, className, ariaLabel, role, url, method }) {
+  const signals = [];
+  let score = 0;
+
+  const t = `${text || ""}`.toLowerCase();
+  const cls = `${className || ""}`.toLowerCase();
+  const aria = `${ariaLabel || ""}`.toLowerCase();
+  const r = `${role || ""}`.toLowerCase();
+  const u = `${url || ""}`.toLowerCase();
+  const m = `${method || ""}`.toUpperCase();
+
+  // Text patterns
+  for (const pattern of DANGER_TEXT_PATTERNS) {
+    if (pattern.test(t) || pattern.test(aria)) {
+      signals.push({ type: "text", value: pattern.source, weight: 0.3 });
+      score += 0.3;
+    }
+  }
+
+  // Class patterns
+  for (const pattern of DANGER_CLASS_PATTERNS) {
+    if (pattern.test(cls)) {
+      signals.push({ type: "class", value: pattern.source, weight: 0.25 });
+      score += 0.25;
+    }
+  }
+
+  // ARIA patterns
+  if (r === "alertdialog") {
+    signals.push({ type: "aria", value: "role=alertdialog", weight: 0.2 });
+    score += 0.2;
+  }
+
+  // Network patterns (DELETE method or destructive endpoints)
+  if (m === "DELETE") {
+    signals.push({ type: "network", value: "DELETE method", weight: 0.4 });
+    score += 0.4;
+  }
+  if (/\/delete\b|\/destroy\b|\/deactivate\b|\/remove\b/.test(u)) {
+    signals.push({ type: "network", value: "destructive endpoint", weight: 0.35 });
+    score += 0.35;
+  }
+
+  const dangerous = score >= 0.25;
+  const reason = signals.length > 0 ? signals[0].type : "none";
+
+  return {
+    dangerous,
+    score: Math.min(1, score),
+    signals,
+    reason,
+  };
+}
+
+// ============================================================================
+// Screenshots & DOM Snapshots
+// ============================================================================
+
+async function screenshot(page, outPath) {
+  try {
+    await page.screenshot({ path: outPath, fullPage: true });
+  } catch {
+    // Non-fatal
+  }
+}
+
+async function domSnapshot(page) {
+  try {
+    return await page.evaluate(() => {
+      const el = document.activeElement;
+      return {
+        url: location.href,
+        title: document.title,
+        active: el ? { tag: el.tagName, id: el.id, name: el.getAttribute("name") } : null,
+        bodyTextSample: document.body?.innerText?.slice(0, 500) || "",
+      };
+    });
+  } catch {
+    return null;
+  }
+}
+
+// ============================================================================
+// Navigation Helpers
+// ============================================================================
+
+async function safeGoto(page, url, timeout) {
+  const started = Date.now();
+  try {
+    const res = await page.goto(url, { waitUntil: "domcontentloaded", timeout });
+    await page.waitForLoadState("networkidle", { timeout: Math.min(timeout, 5000) }).catch(() => {});
+    const status = res ? res.status() : 0;
+    return { ok: status >= 200 && status < 400, status, ms: Date.now() - started };
+  } catch (e) {
+    return { ok: false, status: 0, ms: Date.now() - started, error: String(e?.message || e).slice(0, 180) };
+  }
+}
+
+async function findLocator(page, target) {
+  return page.locator(target).first();
+}
+
+// ============================================================================
+// Surface Discovery
+// ============================================================================
+
+async function discoverSurface({ page, baseUrl, timeout, maxPages }) {
+  const discovered = {
+    routes: [],
+    elements: [],
+    forms: [],
+  };
+
+  // Visit base
+  const home = await safeGoto(page, baseUrl, timeout);
+  if (home.status) {
+    discovered.routes.push({ path: "/", status: home.ok ? "success" : "error", httpStatus: home.status });
+  }
+
+  // Extract routes
+  const routes = await page.evaluate(() => {
+    const out = new Set();
+    document.querySelectorAll("a[href]").forEach(a => {
+      const href = a.getAttribute("href") || "";
+      if (!href || href.startsWith("http") || href.startsWith("//") || href.includes("#")) return;
+      if (href.startsWith("/")) out.add(href);
+    });
+    // Common SPA routes
+    ["/dashboard", "/app", "/account", "/settings", "/profile", "/projects", "/analytics", "/billing"].forEach(r => out.add(r));
+    return Array.from(out);
+  }).catch(() => []);
+
+  const queue = routes.slice(0, maxPages * 2);
+  const seen = new Set(["/", baseUrl]);
+
+  for (const route of queue.slice(0, maxPages)) {
+    if (seen.has(route)) continue;
+    seen.add(route);
+
+    const res = await safeGoto(page, baseUrl + route, timeout);
+    discovered.routes.push({
+      path: route,
+      status: res.ok ? "success" : "error",
+      httpStatus: res.status || 0,
+      error: res.error,
+    });
+
+    // Discover elements on this page
+    const pageEls = await page.evaluate(() => {
+      const pickText = (el) => (el.textContent || el.getAttribute("aria-label") || "").trim().slice(0, 80);
+      const els = Array.from(document.querySelectorAll('button, [role="button"], input[type="submit"], a[href], [data-testid]'));
+      return els.slice(0, 100).map((el, idx) => ({
+        tag: el.tagName.toLowerCase(),
+        text: pickText(el),
+        id: el.id || "",
+        testid: el.getAttribute("data-testid") || "",
+        className: el.className || "",
+        ariaLabel: el.getAttribute("aria-label") || "",
+        href: el.getAttribute("href") || "",
+        index: idx,
+      }));
+    }).catch(() => []);
+
+    for (const e of pageEls) {
+      if (!e.text && !e.testid && !e.id) continue;
+      discovered.elements.push({ ...e, page: route });
+    }
+
+    // Discover forms
+    const forms = await page.evaluate(() => {
+      const forms = Array.from(document.querySelectorAll("form"));
+      return forms.slice(0, 20).map((form, idx) => {
+        const fields = Array.from(form.querySelectorAll("input, textarea, select")).slice(0, 30).map((f) => ({
+          name: f.getAttribute("name") || f.id || "",
+          type: f.getAttribute("type") || f.tagName.toLowerCase(),
+          required: !!f.required,
+        }));
+        return {
+          selector: form.id ? `#${form.id}` : form.getAttribute("data-testid") ? `[data-testid="${form.getAttribute("data-testid")}"]` : `form:nth-of-type(${idx + 1})`,
+          fields,
+        };
+      });
+    }).catch(() => []);
+
+    for (const f of forms) discovered.forms.push({ ...f, page: route });
+  }
+
+  // Dedupe
+  discovered.routes = dedupe(discovered.routes, r => r.path);
+  discovered.elements = dedupe(discovered.elements, e => `${e.page}|${e.tag}|${e.testid}|${e.id}|${e.text}`);
+  discovered.forms = dedupe(discovered.forms, f => `${f.page}|${f.selector}`);
+
+  return discovered;
+}
+
+function dedupe(arr, keyFn) {
+  const seen = new Set();
+  const out = [];
+  for (const x of arr) {
+    const k = keyFn(x);
+    if (seen.has(k)) continue;
+    seen.add(k);
+    out.push(x);
+  }
+  return out;
+}
+
+// ============================================================================
+// Flow Plan Execution
+// ============================================================================
+
+async function runFlowPlan({ plan, page, context, telemetry }) {
+  const results = {
+    meta: {
+      baseUrl: plan.baseUrl,
+      startedAt: new Date().toISOString(),
+      danger: plan.danger,
+      maxPages: plan.maxPages,
+      timeout: plan.timeout,
+    },
+    discovery: null,
+    coverage: {
+      routesDiscovered: 0,
+      routesWorking: 0,
+      elementsDiscovered: 0,
+      elementsWorking: 0,
+      formsDiscovered: 0,
+      formsWorking: 0,
+    },
+    flows: [],
+    routes: [],
+    elements: [],
+    forms: [],
+    errors: [],
+    network: [],
+    console: [],
+    timeline: [],
+    score: 0,
+    duration: 0,
+  };
+
+  // Discovery pass
+  const discovery = await discoverSurface({
+    page,
+    baseUrl: plan.baseUrl,
+    timeout: plan.timeout,
+    maxPages: plan.maxPages,
+  });
+
+  results.discovery = {
+    routes: discovery.routes.length,
+    elements: discovery.elements.length,
+    forms: discovery.forms.length,
+  };
+
+  results.routes = discovery.routes;
+  results.elements = discovery.elements;
+  results.forms = discovery.forms;
+
+  results.coverage.routesDiscovered = discovery.routes.length;
+  results.coverage.routesWorking = discovery.routes.filter(r => r.status === "success").length;
+  results.coverage.elementsDiscovered = discovery.elements.length;
+  results.coverage.formsDiscovered = discovery.forms.length;
+
+  // Collect telemetry
+  results.console = telemetry.console.slice(-500);
+  results.errors = [
+    ...telemetry.pageErrors.map(e => ({ type: "uncaught", message: e.message, url: e.url, ts: e.ts })),
+    ...telemetry.console.filter(m => m.type === "error").map(m => ({ type: "console", message: m.text, url: m.url, ts: m.ts })),
+  ];
+  results.network = telemetry.responses.slice(-500);
+
+  // Run Flow Packs
+  const flowVarsBase = makeBaseVars(plan);
+  const flowsToRun = Array.isArray(plan.flows) ? plan.flows : [];
+
+  for (const flow of flowsToRun) {
+    const flowResult = await runSingleFlow({
+      flow,
+      plan,
+      page,
+      context,
+      telemetry,
+      varsBase: flowVarsBase,
+      results,
+    });
+    results.flows.push(flowResult);
+  }
+
+  // Count working elements from successful flow steps
+  let elementWorking = 0;
+  for (const f of results.flows) {
+    for (const s of (f.steps || [])) {
+      if ((s.action === "click" || s.action === "fill") && s.status === "success") elementWorking++;
+    }
+  }
+  results.coverage.elementsWorking = Math.min(elementWorking, results.coverage.elementsDiscovered);
+
+  // Calculate score
+  results.score = calculateScore(results);
+
+  return results;
+}
+
+function makeBaseVars(plan) {
+  const vars = {
+    baseUrl: plan.baseUrl,
+    timestamp: String(Date.now()),
+    $timestamp: String(Date.now()),
+    $uuid: uuid(),
+    $randomEmail: randomEmail(),
+    $isoDate: new Date().toISOString(),
+  };
+
+  if (plan.auth && typeof plan.auth === "string" && plan.auth.includes(":")) {
+    const [email, ...rest] = plan.auth.split(":");
+    vars.email = email;
+    vars.password = rest.join(":");
+  }
+
+  return vars;
+}
+
+// ============================================================================
+// Single Flow Execution
+// ============================================================================
+
+async function runSingleFlow({ flow, plan, page, telemetry, varsBase, results }) {
+  const flowStart = Date.now();
+  const flowVars = { ...varsBase, ...(flow.vars || {}) };
+
+  // Template all vars
+  for (const k of Object.keys(flowVars)) {
+    flowVars[k] = template(flowVars[k], flowVars);
+  }
+
+  const flowOut = {
+    id: flow.id,
+    name: flow.name,
+    source: flow.__source,
+    required: !!flow.required,
+    status: "success",
+    startedAt: new Date(flowStart).toISOString(),
+    durationMs: 0,
+    steps: [],
+    assertions: [],
+    errors: [],
+  };
+
+  // Run steps
+  let stepIndex = 0;
+  for (const step of flow.steps || []) {
+    stepIndex++;
+    const stepId = `${flow.id}#${stepIndex}`;
+    const stepName = step.name || `${step.action || "step"}-${stepIndex}`;
+    const stepStart = Date.now();
+
+    const stepRec = {
+      id: stepId,
+      name: stepName,
+      action: step.action,
+      target: step.target || null,
+      status: "success",
+      error: null,
+      danger: null,
+      artifacts: {},
+      startedAt: new Date(stepStart).toISOString(),
+      durationMs: 0,
+    };
+
+    // Trace marker
+    try {
+      await page.evaluate((label) => console.log(`[reality:trace] ${label}`), `STEP ${stepId}`);
+    } catch {}
+
+    // Before screenshot
+    const beforeShot = path.join(plan.artifacts.screenshotsDir, `${flow.id}__${stepIndex}__before.png`);
+    await screenshot(page, beforeShot);
+    stepRec.artifacts.beforeScreenshot = path.relative(plan.outputDir, beforeShot);
+    stepRec.artifacts.beforeDom = await domSnapshot(page);
+
+    // Execute action
+    try {
+      await executeStep({ step, stepRec, plan, page, flowVars, telemetry });
+    } catch (e) {
+      stepRec.status = "error";
+      stepRec.error = String(e?.message || e).slice(0, 220);
+      flowOut.errors.push({ step: stepIndex, message: stepRec.error });
+    }
+
+    // After screenshot
+    const afterShot = path.join(plan.artifacts.screenshotsDir, `${flow.id}__${stepIndex}__after.png`);
+    await screenshot(page, afterShot);
+    stepRec.artifacts.afterScreenshot = path.relative(plan.outputDir, afterShot);
+    stepRec.artifacts.afterDom = await domSnapshot(page);
+
+    stepRec.durationMs = Date.now() - stepStart;
+
+    // Add to timeline
+    results.timeline.push({
+      flowId: flow.id,
+      step: stepIndex,
+      name: stepRec.name,
+      action: stepRec.action,
+      status: stepRec.status,
+      at: Date.now(),
+      url: page.url(),
+      before: stepRec.artifacts.beforeScreenshot,
+      after: stepRec.artifacts.afterScreenshot,
+    });
+
+    flowOut.steps.push(stepRec);
+  }
+
+  // Run assertions
+  for (const a of flow.assertions || []) {
+    const ar = await runAssertion({ assertion: a, plan, page, telemetry, vars: flowVars });
+    flowOut.assertions.push(ar);
+    if (ar.status === "fail" && a.critical) {
+      flowOut.status = "error";
+    }
+  }
+
+  // Cleanup (best-effort)
+  for (const step of flow.cleanup || []) {
+    try {
+      await executeStep({ step, stepRec: {}, plan, page, flowVars, telemetry });
+    } catch {}
+  }
+
+  flowOut.durationMs = Date.now() - flowStart;
+  if (flowOut.errors.length > 0) flowOut.status = "error";
+
+  return flowOut;
+}
+
+// ============================================================================
+// Step Execution
+// ============================================================================
+
+async function executeStep({ step, stepRec, plan, page, flowVars, telemetry }) {
+  const action = String(step.action || "").toLowerCase();
+
+  if (action === "navigate") {
+    const target = template(step.target || "/", flowVars);
+    const url = target.startsWith("http") ? target : (plan.baseUrl + (target.startsWith("/") ? target : `/${target}`));
+    const res = await safeGoto(page, url, plan.timeout);
+    if (!res.ok) throw new Error(res.error || `Navigation failed: ${url}`);
+  }
+
+  else if (action === "wait") {
+    if (step.for === "selector" && step.target) {
+      const target = template(step.target, flowVars);
+      const state = step.state || "visible";
+      const loc = await findLocator(page, target);
+      await loc.waitFor({ state, timeout: Number(step.timeout || plan.timeout) });
+    } else if (step.for === "navigation" && step.match) {
+      const match = new RegExp(template(step.match, flowVars));
+      const timeout = Number(step.timeout || plan.timeout);
+      const end = Date.now() + timeout;
+      while (Date.now() < end) {
+        if (match.test(page.url())) break;
+        await page.waitForTimeout(200);
+      }
+      if (!match.test(page.url())) throw new Error(`URL did not match ${step.match}`);
+    } else if (step.for === "network" && step.match) {
+      const match = template(step.match, flowVars);
+      const timeout = Number(step.timeout || plan.timeout);
+      const since = Date.now();
+      const end = since + timeout;
+      let found = false;
+      while (Date.now() < end) {
+        const recent = telemetry.responses.filter(r => r.ts >= since);
+        if (recent.some(r => r.url.includes(match))) { found = true; break; }
+        await page.waitForTimeout(200);
+      }
+      if (!found) throw new Error(`No network call matching ${match}`);
+    } else {
+      const ms = Number(step.timeout || step.ms || 1000);
+      await page.waitForTimeout(ms);
+    }
+  }
+
+  else if (action === "fill") {
+    const target = template(step.target, flowVars);
+    const value = template(step.value, flowVars);
+    const loc = await findLocator(page, target);
+    await loc.waitFor({ state: "visible", timeout: plan.timeout }).catch(() => {});
+    if (step.clear !== false) await loc.clear().catch(() => {});
+    await loc.fill(String(value ?? ""), { timeout: plan.timeout });
+  }
+
+  else if (action === "click") {
+    const target = template(step.target, flowVars);
+    const loc = await findLocator(page, target);
+
+    // Danger detection
+    let meta = {};
+    try {
+      meta = await loc.evaluate((el) => ({
+        text: (el.textContent || "").trim().slice(0, 120),
+        className: el.className || "",
+        ariaLabel: el.getAttribute("aria-label") || "",
+        role: el.getAttribute("role") || "",
+      }));
+    } catch {}
+
+    const danger = classifyDanger({ ...meta, url: page.url() });
+    stepRec.danger = danger;
+
+    const policy = String(step.dangerPolicy || "skip").toLowerCase();
+    if (danger.dangerous && !plan.danger) {
+      if (policy === "block") {
+        stepRec.status = "blocked";
+        stepRec.error = `Blocked destructive action (${danger.reason}). Use --danger to allow.`;
+        return;
+      }
+      stepRec.status = "skipped";
+      stepRec.error = `Skipped destructive action (${danger.reason}). Use --danger to allow.`;
+      return;
+    }
+
+    await loc.waitFor({ state: "visible", timeout: plan.timeout }).catch(() => {});
+    try {
+      await loc.click({ timeout: plan.timeout });
+    } catch {
+      await loc.click({ timeout: plan.timeout, force: true });
+    }
+    await page.waitForTimeout(300);
+  }
+
+  else if (action === "check") {
+    const target = template(step.target, flowVars);
+    const loc = await findLocator(page, target);
+    await loc.check({ timeout: plan.timeout });
+  }
+
+  else if (action === "uncheck") {
+    const target = template(step.target, flowVars);
+    const loc = await findLocator(page, target);
+    await loc.uncheck({ timeout: plan.timeout });
+  }
+
+  else if (action === "select") {
+    const target = template(step.target, flowVars);
+    const loc = await findLocator(page, target);
+    if (step.value) {
+      await loc.selectOption({ value: template(step.value, flowVars) });
+    } else if (step.label) {
+      await loc.selectOption({ label: template(step.label, flowVars) });
+    } else if (step.index != null) {
+      await loc.selectOption({ index: Number(step.index) });
+    }
+  }
+
+  else if (action === "hover") {
+    const target = template(step.target, flowVars);
+    const loc = await findLocator(page, target);
+    await loc.hover({ timeout: plan.timeout });
+  }
+
+  else if (action === "press") {
+    const key = template(step.key, flowVars);
+    await page.keyboard.press(key);
+  }
+
+  else if (action === "screenshot") {
+    const name = template(step.name || `manual-${Date.now()}`, flowVars);
+    const outPath = path.join(plan.artifacts.screenshotsDir, `${name}.png`);
+    await screenshot(page, outPath);
+    stepRec.artifacts.manualScreenshot = path.relative(plan.outputDir, outPath);
+  }
+
+  else if (action === "scroll") {
+    if (step.to === "bottom") {
+      await page.evaluate(() => window.scrollTo(0, document.body.scrollHeight));
+    } else if (step.to === "top") {
+      await page.evaluate(() => window.scrollTo(0, 0));
+    } else if (step.target) {
+      const target = template(step.target, flowVars);
+      const loc = await findLocator(page, target);
+      await loc.scrollIntoViewIfNeeded();
+    }
+  }
+
+  else if (action === "execute") {
+    if (step.script) {
+      await page.evaluate(step.script);
+    } else if (step.scriptFile) {
+      const scriptPath = path.resolve(step.scriptFile);
+      const script = fs.readFileSync(scriptPath, "utf8");
+      await page.evaluate(script);
+    }
+  }
+
+  else {
+    stepRec.status = "unknown";
+    stepRec.error = `Unknown action: ${step.action}`;
+  }
+}
+
+// ============================================================================
+// Assertions
+// ============================================================================
+
+async function runAssertion({ assertion, plan, page, telemetry, vars }) {
+  const type = String(assertion.type || "").toLowerCase().replace(/-/g, "");
+  const critical = !!assertion.critical;
+
+  const out = {
+    type: assertion.type,
+    critical,
+    status: "pass",
+    message: "",
+  };
+
+  try {
+    if (type === "urlcontains") {
+      const v = template(assertion.value, vars);
+      if (!page.url().toLowerCase().includes(v.toLowerCase())) {
+        throw new Error(`URL does not contain: ${v} (got ${page.url()})`);
+      }
+    }
+
+    else if (type === "urlmatches") {
+      const v = template(assertion.pattern || assertion.value, vars);
+      const re = new RegExp(v);
+      if (!re.test(page.url())) throw new Error(`URL does not match: ${v}`);
+    }
+
+    else if (type === "urlnotcontains") {
+      const v = template(assertion.value, vars);
+      if (page.url().toLowerCase().includes(v.toLowerCase())) {
+        throw new Error(`URL should not contain: ${v}`);
+      }
+    }
+
+    else if (type === "routechanged") {
+      const within = Number(assertion.within || 3000);
+      const match = assertion.match ? new RegExp(template(assertion.match, vars)) : null;
+      const before = page.url();
+      await page.waitForTimeout(Math.min(within, 500));
+      const after = page.url();
+      if (after === before) throw new Error(`Route did not change`);
+      if (match && !match.test(after)) throw new Error(`Route changed but does not match: ${assertion.match}`);
+    }
+
+    else if (type === "elementvisible") {
+      const target = template(assertion.target, vars);
+      const loc = await findLocator(page, target);
+      await loc.waitFor({ state: "visible", timeout: Number(assertion.within || plan.timeout) });
+    }
+
+    else if (type === "elementhidden") {
+      const target = template(assertion.target, vars);
+      const loc = await findLocator(page, target);
+      await loc.waitFor({ state: "hidden", timeout: Number(assertion.within || plan.timeout) });
+    }
+
+    else if (type === "elementtext") {
+      const target = template(assertion.target, vars);
+      const loc = await findLocator(page, target);
+      const text = await loc.textContent({ timeout: plan.timeout });
+      if (assertion.contains) {
+        const expected = template(assertion.contains, vars);
+        if (!String(text || "").includes(expected)) {
+          throw new Error(`Element text does not contain "${expected}"`);
+        }
+      }
+      if (assertion.matches) {
+        const re = new RegExp(template(assertion.matches, vars));
+        if (!re.test(text || "")) {
+          throw new Error(`Element text does not match ${assertion.matches}`);
+        }
+      }
+    }
+
+    else if (type === "elementcount") {
+      const target = template(assertion.target, vars);
+      const count = await page.locator(target).count();
+      if (assertion.min != null && count < assertion.min) {
+        throw new Error(`Element count ${count} < min ${assertion.min}`);
+      }
+      if (assertion.max != null && count > assertion.max) {
+        throw new Error(`Element count ${count} > max ${assertion.max}`);
+      }
+      if (assertion.equals != null && count !== assertion.equals) {
+        throw new Error(`Element count ${count} !== ${assertion.equals}`);
+      }
+    }
+
+    else if (type === "toastcontains" || type === "notificationvisible") {
+      const v = template(assertion.text || assertion.contains || assertion.value, vars);
+      const within = Number(assertion.within || 5000);
+      const toastSel = assertion.target || '[role="status"], [role="alert"], .toast, .sonner-toast, [data-sonner-toast], .notification';
+      const loc = page.locator(toastSel).filter({ hasText: new RegExp(v, "i") }).first();
+      await loc.waitFor({ state: "visible", timeout: within });
+    }
+
+    else if (type === "toastnotcontains") {
+      const v = template(assertion.text || assertion.value, vars);
+      const within = Number(assertion.within || 3000);
+      const toastSel = assertion.target || '[role="status"], [role="alert"], .toast, .sonner-toast, [data-sonner-toast], .notification';
+      await page.waitForTimeout(Math.min(within, 1500));
+      const count = await page.locator(toastSel).filter({ hasText: new RegExp(v, "i") }).count();
+      if (count > 0) throw new Error(`Toast contains forbidden text: ${v}`);
+    }
+
+    else if (type === "networkcalled") {
+      const v = template(assertion.match || assertion.value, vars);
+      const within = Number(assertion.within || 10000);
+      const minTimes = assertion.times ?? assertion.minTimes ?? 1;
+      const since = Date.now() - within;
+      const matches = telemetry.responses.filter(r => r.ts >= since && r.url.includes(v));
+      if (matches.length < minTimes) {
+        throw new Error(`Expected ${minTimes} calls matching ${v}, got ${matches.length}`);
+      }
+    }
+
+    else if (type === "networkstatus") {
+      const v = template(assertion.match || assertion.value, vars);
+      const expectStatus = Number(assertion.status || 200);
+      const within = Number(assertion.within || 10000);
+      const since = Date.now() - within;
+      const match = telemetry.responses.find(r => r.ts >= since && r.url.includes(v));
+      if (!match) throw new Error(`No response matching: ${v}`);
+      if (match.status !== expectStatus) {
+        throw new Error(`Expected ${expectStatus}, got ${match.status} for ${match.url}`);
+      }
+    }
+
+    else if (type === "networktiming") {
+      const v = template(assertion.match || assertion.value, vars);
+      const maxDuration = Number(assertion.maxDuration || 5000);
+      // Check request/response pairs - simplified version
+      const match = telemetry.responses.find(r => r.url.includes(v));
+      if (!match) throw new Error(`No response matching: ${v}`);
+      // We don't have timing data in this simplified version
+      out.message = `Network timing check (simplified): ${v}`;
+    }
+
+    else if (type === "noconsoleerrors") {
+      const severity = String(assertion.severity || "error").toLowerCase();
+      const windowMs = Number(assertion.within || 60000);
+      const since = Date.now() - windowMs;
+
+      const ignorePatterns = (assertion.ignore || []).map(p => new RegExp(p));
+      
+      const bad = telemetry.console
+        .filter(m => m.ts >= since)
+        .filter(m => {
+          if (severity === "error") return m.type === "error";
+          if (severity === "warning" || severity === "warn") return m.type === "error" || m.type === "warning";
+          return m.type === "error";
+        })
+        .filter(m => !ignorePatterns.some(re => re.test(m.text)));
+
+      if (bad.length > 0) {
+        throw new Error(`Console ${bad[0].type}: ${String(bad[0].text || "").slice(0, 140)}`);
+      }
+    }
+
+    else if (type === "consolecontains") {
+      const match = template(assertion.match || assertion.value, vars);
+      const severity = String(assertion.severity || "log").toLowerCase();
+      const found = telemetry.console.some(m => {
+        if (severity !== "all" && m.type !== severity) return false;
+        return m.text.includes(match);
+      });
+      if (!found) throw new Error(`Console does not contain: ${match}`);
+    }
+
+    else if (type === "localstorage") {
+      const key = template(assertion.key, vars);
+      const value = await page.evaluate((k) => localStorage.getItem(k), key);
+      if (assertion.exists === true && value === null) {
+        throw new Error(`localStorage key "${key}" does not exist`);
+      }
+      if (assertion.exists === false && value !== null) {
+        throw new Error(`localStorage key "${key}" should not exist`);
+      }
+      if (assertion.equals != null && value !== assertion.equals) {
+        throw new Error(`localStorage "${key}" !== "${assertion.equals}"`);
+      }
+      if (assertion.matches) {
+        const re = new RegExp(assertion.matches);
+        if (!re.test(value || "")) throw new Error(`localStorage "${key}" does not match ${assertion.matches}`);
+      }
+    }
+
+    else if (type === "sessionstorage") {
+      const key = template(assertion.key, vars);
+      const value = await page.evaluate((k) => sessionStorage.getItem(k), key);
+      if (assertion.exists === true && value === null) {
+        throw new Error(`sessionStorage key "${key}" does not exist`);
+      }
+      if (assertion.matches) {
+        const re = new RegExp(assertion.matches);
+        if (!re.test(value || "")) throw new Error(`sessionStorage "${key}" does not match ${assertion.matches}`);
+      }
+    }
+
+    else {
+      out.status = "skip";
+      out.message = `Assertion type not implemented: ${assertion.type}`;
+    }
+  } catch (e) {
+    out.status = "fail";
+    out.message = String(e?.message || e).slice(0, 220);
+  }
+
+  return out;
+}
+
+// ============================================================================
+// Score Calculation
+// ============================================================================
+
+function calculateScore(results) {
+  const routesDiscovered = results.coverage?.routesDiscovered || 0;
+  const routesWorking = results.coverage?.routesWorking || 0;
+  const routePct = routesDiscovered ? (routesWorking / routesDiscovered) : 1;
+
+  const flows = results.flows || [];
+  const flowTotal = flows.length || 1;
+  const flowOk = flows.filter(f => f.status === "success").length;
+
+  let assertsTotal = 0;
+  let assertsPass = 0;
+  for (const f of flows) {
+    for (const a of (f.assertions || [])) {
+      if (a.status === "skip") continue;
+      assertsTotal++;
+      if (a.status === "pass") assertsPass++;
+    }
+  }
+  const assertPct = assertsTotal ? (assertsPass / assertsTotal) : 1;
+
+  const errors = results.errors?.length || 0;
+  const penalty = Math.min(errors * 3, 20);
+
+  const score = (routePct * 30) + ((flowOk / flowTotal) * 40) + (assertPct * 30) - penalty;
+
+  return Math.max(0, Math.min(100, Math.round(score)));
+}
+
+module.exports = { runFlowPlan, classifyDanger, discoverSurface };