assuremind 1.2.1 → 1.2.3

package/dist/cli/index.js

@@ -353,8 +353,8 @@ async function runInit(options = {}) {
     printSuccess(`  ${jsonFile}`);
   }
   if (!await import_fs_extra.default.pathExists("autotest.config.json")) {
-    const { DEFAULT_CONFIG: DEFAULT_CONFIG2 } = await Promise.resolve().then(() => (init_config(), config_exports));
-    await import_fs_extra.default.writeJson("autotest.config.json", DEFAULT_CONFIG2, { spaces: 2 });
+    const { DEFAULT_CONFIG: DEFAULT_CONFIG3 } = await Promise.resolve().then(() => (init_config(), config_exports));
+    await import_fs_extra.default.writeJson("autotest.config.json", DEFAULT_CONFIG3, { spaces: 2 });
     printSuccess("  autotest.config.json");
   } else {
     printSkipped("  autotest.config.json  (already exists)");
@@ -468,10 +468,10 @@ var init_errors = __esm({
     };
     StorageError = class extends AssuremindError {
       path;
-      constructor(message, path37, code = "STORAGE_ERROR") {
+      constructor(message, path41, code = "STORAGE_ERROR") {
         super(message, code);
         this.name = "StorageError";
-        this.path = path37;
+        this.path = path41;
       }
     };
   }
@@ -1162,8 +1162,10 @@ var init_suite = __esm({
       mockStatus: import_zod3.z.number().int().optional(),
       runAudit: import_zod3.z.boolean().optional(),
       // Mark this step as a Lighthouse audit checkpoint
-      soft: import_zod3.z.boolean().optional()
+      soft: import_zod3.z.boolean().optional(),
       // Use expect.soft() — test continues on assertion failure
+      visualCheck: import_zod3.z.boolean().optional()
+      // Enable visual regression comparison for this step
     });
     DataSourceSchema = import_zod3.z.object({
       type: import_zod3.z.enum(["inline", "json-file", "csv-file"]),
@@ -3651,7 +3653,86 @@ When the instruction starts with "Soft verify" or "Soft assert" or "Soft check",
   await expect.soft(page.getByText('Welcome')).toBeVisible()
   await expect.soft(page.getByLabel('Email')).toHaveValue('user@example.com')
 
-For "verify user is on X page" \u2192 use toHaveURL() or check for a heading/element specific to that page.`;
+For "verify user is on X page" \u2192 use toHaveURL() or check for a heading/element specific to that page.
+
+\u2501\u2501\u2501 JAVASCRIPT ALERTS / DIALOGS \u2501\u2501\u2501
+When the step mentions "accept alert", "dismiss alert", "handle popup", "click OK on dialog", "confirm dialog", or "enter text in prompt":
+  // Accept (OK) an alert or confirm dialog
+  page.once('dialog', dialog => dialog.accept());
+  await page.getByRole('button', { name: 'Trigger' }).click();
+
+  // Dismiss (Cancel) a confirm dialog
+  page.once('dialog', dialog => dialog.dismiss());
+  await page.getByRole('button', { name: 'Delete' }).click();
+
+  // Accept a prompt and provide text
+  page.once('dialog', dialog => dialog.accept('my input text'));
+  await page.getByRole('button', { name: 'Ask' }).click();
+
+  // Assert dialog message
+  page.once('dialog', async dialog => {
+    expect(dialog.message()).toContain('Are you sure?');
+    await dialog.accept();
+  });
+
+IMPORTANT: Register the dialog handler with page.once() BEFORE the action that triggers it.
+
+\u2501\u2501\u2501 SHADOW DOM \u2501\u2501\u2501
+For elements inside a Shadow Root, use Playwright's CSS pierce combinator (>>):
+  // Click a button inside shadow root
+  await page.locator('my-component >> button').click();
+  await page.locator('my-component >> [data-testid="submit"]').click();
+
+  // Fill an input inside shadow root
+  await page.locator('custom-input >> input').fill('value');
+
+  // Deep shadow DOM (multiple levels)
+  await page.locator('outer-element >> inner-element >> button').click();
+
+  // Using :host selector
+  await page.locator(':shadow(my-component) >> input').fill('text');
+
+When elements are inside a shadow root, use locator() with >> combinator instead of getBy methods.
+
+\u2501\u2501\u2501 IFRAMES \u2501\u2501\u2501
+For elements inside an <iframe>, use frameLocator() to enter the frame context:
+  // Click inside iframe
+  await page.frameLocator('iframe[name="myFrame"]').getByRole('button', { name: 'Submit' }).click();
+  await page.frameLocator('#iframe-id').getByLabel('Username').fill('admin');
+  await page.frameLocator('iframe[src*="payment"]').getByPlaceholder('Card number').fill('4111111111111111');
+
+  // Multiple iframes \u2014 chain frameLocator
+  await page.frameLocator('iframe.outer').frameLocator('iframe.inner').getByRole('button').click();
+
+Use frameLocator() for ALL interactions inside iframes \u2014 both click AND fill operations work.
+
+\u2501\u2501\u2501 KEYBOARD ACTIONS \u2501\u2501\u2501
+For keyboard-specific steps (press key, keyboard shortcut, type text):
+  // Press a single key
+  await page.keyboard.press('Enter');
+  await page.keyboard.press('Escape');
+  await page.keyboard.press('Tab');
+  await page.keyboard.press('ArrowDown');
+  await page.keyboard.press('Space');
+  await page.keyboard.press('Backspace');
+  await page.keyboard.press('Delete');
+
+  // Keyboard shortcuts (modifier + key)
+  await page.keyboard.press('Control+A');   // Select all
+  await page.keyboard.press('Control+C');   // Copy
+  await page.keyboard.press('Control+V');   // Paste
+  await page.keyboard.press('Control+Z');   // Undo
+  await page.keyboard.press('Shift+Tab');   // Shift+Tab (go back)
+  await page.keyboard.press('Alt+F4');
+
+  // Type text character by character (simulates real keystrokes)
+  await page.keyboard.type('Hello World');
+
+  // Press key on a specific element (focus first)
+  await page.getByLabel('Search').press('Enter');
+  await page.getByRole('textbox').press('Control+A');
+
+Use page.keyboard.press() for single keys or shortcuts, page.keyboard.type() when the step says "type using keyboard".`;
   }
 });
 
@@ -5598,6 +5679,7 @@ async function stepRoutes(fastify) {
             }
           }
         }
+        if (parsed.data.visualCheck !== void 0) patch.visualCheck = parsed.data.visualCheck;
         return { ...s, ...patch };
       });
       const updated = await updateCase(caseDir, { steps: updatedSteps });
@@ -5643,7 +5725,8 @@ var init_steps = __esm({
       auditUrl: import_zod8.z.string().optional(),
       lighthouseCategories: import_zod8.z.array(import_zod8.z.enum(["performance", "accessibility", "seo"])).optional(),
       runAudit: import_zod8.z.boolean().optional(),
-      soft: import_zod8.z.boolean().optional()
+      soft: import_zod8.z.boolean().optional(),
+      visualCheck: import_zod8.z.boolean().optional()
     });
   }
 });
@@ -6354,8 +6437,8 @@ async function healingRoutes(fastify) {
       return reply.status(400).send({ error: "Invalid request", details: parsed.error.issues });
     }
     try {
-      const { default: fs30 } = await import("fs-extra");
-      const report = await fs30.readJson(parsed.data.reportPath);
+      const { default: fs34 } = await import("fs-extra");
+      const report = await fs34.readJson(parsed.data.reportPath);
       if (!Array.isArray(report.events)) {
         return reply.status(400).send({ error: "Invalid healing report format" });
       }
@@ -6390,7 +6473,7 @@ async function applyHealToCase(testsDir, caseId, stepId, healedCode) {
   await updateCase(casePath, { steps: updatedSteps });
 }
 async function findCasePath(testsDir, caseId) {
-  const { default: fs30 } = await import("fs-extra");
+  const { default: fs34 } = await import("fs-extra");
   const { listSuiteDirs: listSuiteDirs2 } = await Promise.resolve().then(() => (init_suite_store(), suite_store_exports));
   const suiteDirs = await listSuiteDirs2(testsDir);
   for (const suiteDir of suiteDirs) {
@@ -6971,8 +7054,8 @@ function normalizeUrl2(url) {
   if (!url) return "";
   try {
     const u = new URL(url);
-    const path37 = u.pathname.replace(/\/\d+/g, "/*");
-    return `${u.hostname}${path37}`;
+    const path41 = u.pathname.replace(/\/\d+/g, "/*");
+    return `${u.hostname}${path41}`;
   } catch {
     return url;
   }
@@ -8279,139 +8362,256 @@ var init_allure_generator = __esm({
   }
 });
 
-// src/utils/faker.ts
-function pick(arr) {
-  return arr[Math.floor(Math.random() * arr.length)];
-}
-function fakeFirstName() {
-  return pick(FIRST_NAMES);
-}
-function fakeLastName() {
-  return pick(LAST_NAMES);
-}
-function fakeAge() {
-  return String(Math.floor(Math.random() * 63) + 18);
-}
-function fakeEmail() {
-  const first = fakeFirstName().toLowerCase();
-  const last = fakeLastName().toLowerCase();
-  const rand = Math.floor(Math.random() * 900) + 100;
-  return `${first}.${last}${rand}@${pick(EMAIL_DOMAINS)}`;
-}
-function fakePhone() {
-  const area = Math.floor(Math.random() * 800) + 200;
-  const prefix = Math.floor(Math.random() * 800) + 200;
-  const line = Math.floor(Math.random() * 9e3) + 1e3;
-  return `${area}-${prefix}-${line}`;
-}
-function fakePassword() {
-  const upper = "ABCDEFGHJKLMNPQRSTUVWXYZ";
-  const lower = "abcdefghjkmnpqrstuvwxyz";
-  const digits = "23456789";
-  const special = "!@#$%^&*";
-  const all = upper + lower + digits + special;
-  const len = Math.floor(Math.random() * 5) + 10;
-  let pwd = pick([...upper]) + pick([...lower]) + pick([...digits]) + pick([...special]);
-  for (let i = pwd.length; i < len; i++) pwd += pick([...all]);
-  return pwd.split("").sort(() => Math.random() - 0.5).join("");
-}
-function fakeNumber(digits) {
-  const d = Math.max(1, digits);
-  const min = d === 1 ? 0 : Math.pow(10, d - 1);
-  const max = Math.pow(10, d) - 1;
-  return String(Math.floor(Math.random() * (max - min + 1)) + min);
+// src/engine/data-generator.ts
+function getAvailableGenerators() {
+  return [
+    {
+      category: "person",
+      methods: [
+        { name: "fullName", example: import_faker.faker.person.fullName() },
+        { name: "firstName", example: import_faker.faker.person.firstName() },
+        { name: "lastName", example: import_faker.faker.person.lastName() },
+        { name: "middleName", example: import_faker.faker.person.middleName() },
+        { name: "sex", example: import_faker.faker.person.sex() },
+        { name: "prefix", example: import_faker.faker.person.prefix() },
+        { name: "suffix", example: import_faker.faker.person.suffix() },
+        { name: "jobTitle", example: import_faker.faker.person.jobTitle() },
+        { name: "jobArea", example: import_faker.faker.person.jobArea() },
+        { name: "jobType", example: import_faker.faker.person.jobType() },
+        { name: "bio", example: import_faker.faker.person.bio() }
+      ]
+    },
+    {
+      category: "internet",
+      methods: [
+        { name: "email", example: import_faker.faker.internet.email() },
+        { name: "userName", example: import_faker.faker.internet.username() },
+        { name: "password", example: import_faker.faker.internet.password() },
+        { name: "url", example: import_faker.faker.internet.url() },
+        { name: "domainName", example: import_faker.faker.internet.domainName() },
+        { name: "domainWord", example: import_faker.faker.internet.domainWord() },
+        { name: "ip", example: import_faker.faker.internet.ip() },
+        { name: "ipv6", example: import_faker.faker.internet.ipv6() },
+        { name: "mac", example: import_faker.faker.internet.mac() },
+        { name: "userAgent", example: import_faker.faker.internet.userAgent() },
+        { name: "emoji", example: import_faker.faker.internet.emoji() }
+      ]
+    },
+    {
+      category: "phone",
+      methods: [
+        { name: "number", example: import_faker.faker.phone.number() },
+        { name: "imei", example: import_faker.faker.phone.imei() }
+      ]
+    },
+    {
+      category: "location",
+      methods: [
+        { name: "streetAddress", example: import_faker.faker.location.streetAddress() },
+        { name: "street", example: import_faker.faker.location.street() },
+        { name: "city", example: import_faker.faker.location.city() },
+        { name: "state", example: import_faker.faker.location.state() },
+        { name: "zipCode", example: import_faker.faker.location.zipCode() },
+        { name: "country", example: import_faker.faker.location.country() },
+        { name: "countryCode", example: import_faker.faker.location.countryCode() },
+        { name: "county", example: import_faker.faker.location.county() },
+        { name: "latitude", example: String(import_faker.faker.location.latitude()) },
+        { name: "longitude", example: String(import_faker.faker.location.longitude()) },
+        { name: "timeZone", example: import_faker.faker.location.timeZone() },
+        { name: "buildingNumber", example: import_faker.faker.location.buildingNumber() }
+      ]
+    },
+    {
+      category: "company",
+      methods: [
+        { name: "name", example: import_faker.faker.company.name() },
+        { name: "catchPhrase", example: import_faker.faker.company.catchPhrase() },
+        { name: "buzzPhrase", example: import_faker.faker.company.buzzPhrase() },
+        { name: "buzzNoun", example: import_faker.faker.company.buzzNoun() },
+        { name: "buzzVerb", example: import_faker.faker.company.buzzVerb() },
+        { name: "buzzAdjective", example: import_faker.faker.company.buzzAdjective() }
+      ]
+    },
+    {
+      category: "finance",
+      methods: [
+        { name: "accountNumber", example: import_faker.faker.finance.accountNumber() },
+        { name: "accountName", example: import_faker.faker.finance.accountName() },
+        { name: "creditCardNumber", example: import_faker.faker.finance.creditCardNumber() },
+        { name: "creditCardCVV", example: import_faker.faker.finance.creditCardCVV() },
+        { name: "currencyCode", example: import_faker.faker.finance.currencyCode() },
+        { name: "currencyName", example: import_faker.faker.finance.currencyName() },
+        { name: "amount", example: import_faker.faker.finance.amount() },
+        { name: "iban", example: import_faker.faker.finance.iban() },
+        { name: "bic", example: import_faker.faker.finance.bic() },
+        { name: "bitcoinAddress", example: import_faker.faker.finance.bitcoinAddress() },
+        { name: "transactionType", example: import_faker.faker.finance.transactionType() }
+      ]
+    },
+    {
+      category: "date",
+      methods: [
+        { name: "past", example: import_faker.faker.date.past().toISOString() },
+        { name: "future", example: import_faker.faker.date.future().toISOString() },
+        { name: "recent", example: import_faker.faker.date.recent().toISOString() },
+        { name: "soon", example: import_faker.faker.date.soon().toISOString() },
+        { name: "birthdate", example: import_faker.faker.date.birthdate().toISOString() },
+        { name: "month", example: import_faker.faker.date.month() },
+        { name: "weekday", example: import_faker.faker.date.weekday() }
+      ]
+    },
+    {
+      category: "lorem",
+      methods: [
+        { name: "word", example: import_faker.faker.lorem.word() },
+        { name: "words", example: import_faker.faker.lorem.words() },
+        { name: "sentence", example: import_faker.faker.lorem.sentence() },
+        { name: "sentences", example: import_faker.faker.lorem.sentences() },
+        { name: "paragraph", example: import_faker.faker.lorem.paragraph() },
+        { name: "slug", example: import_faker.faker.lorem.slug() },
+        { name: "lines", example: import_faker.faker.lorem.lines(1) }
+      ]
+    },
+    {
+      category: "string",
+      methods: [
+        { name: "uuid", example: import_faker.faker.string.uuid() },
+        { name: "alphanumeric", example: import_faker.faker.string.alphanumeric(10) },
+        { name: "numeric", example: import_faker.faker.string.numeric(6) },
+        { name: "alpha", example: import_faker.faker.string.alpha(8) },
+        { name: "nanoid", example: import_faker.faker.string.nanoid() },
+        { name: "hexadecimal", example: import_faker.faker.string.hexadecimal({ length: 8 }) },
+        { name: "sample", example: import_faker.faker.string.sample(12) }
+      ]
+    },
+    {
+      category: "number",
+      methods: [
+        { name: "int", example: String(import_faker.faker.number.int({ max: 9999 })) },
+        { name: "float", example: String(import_faker.faker.number.float({ max: 100, fractionDigits: 2 })) }
+      ]
+    },
+    {
+      category: "datatype",
+      methods: [
+        { name: "boolean", example: String(import_faker.faker.datatype.boolean()) }
+      ]
+    },
+    {
+      category: "image",
+      methods: [
+        { name: "avatar", example: import_faker.faker.image.avatar() },
+        { name: "url", example: import_faker.faker.image.url() }
+      ]
+    },
+    {
+      category: "color",
+      methods: [
+        { name: "human", example: import_faker.faker.color.human() },
+        { name: "rgb", example: import_faker.faker.color.rgb() },
+        { name: "hex", example: import_faker.faker.color.rgb({ format: "hex" }) }
+      ]
+    },
+    {
+      category: "commerce",
+      methods: [
+        { name: "productName", example: import_faker.faker.commerce.productName() },
+        { name: "price", example: import_faker.faker.commerce.price() },
+        { name: "department", example: import_faker.faker.commerce.department() },
+        { name: "productDescription", example: import_faker.faker.commerce.productDescription().slice(0, 60) + "..." },
+        { name: "isbn", example: import_faker.faker.commerce.isbn() }
+      ]
+    },
+    {
+      category: "vehicle",
+      methods: [
+        { name: "vehicle", example: import_faker.faker.vehicle.vehicle() },
+        { name: "manufacturer", example: import_faker.faker.vehicle.manufacturer() },
+        { name: "model", example: import_faker.faker.vehicle.model() },
+        { name: "vin", example: import_faker.faker.vehicle.vin() },
+        { name: "vrm", example: import_faker.faker.vehicle.vrm() }
+      ]
+    },
+    {
+      category: "system",
+      methods: [
+        { name: "fileName", example: import_faker.faker.system.fileName() },
+        { name: "mimeType", example: import_faker.faker.system.mimeType() },
+        { name: "fileExt", example: import_faker.faker.system.fileExt() },
+        { name: "filePath", example: import_faker.faker.system.filePath() },
+        { name: "semver", example: import_faker.faker.system.semver() }
+      ]
+    }
+  ];
 }
+function callFaker(category, method) {
+  const fakerModule = import_faker.faker[category];
+  const resolvedMethod = METHOD_ALIASES[`${category}.${method}`] ?? method;
+  if (!fakerModule || typeof fakerModule[resolvedMethod] !== "function") {
+    return `[unknown: ${category}.${method}]`;
+  }
+  const result = fakerModule[resolvedMethod]();
+  if (result instanceof Date) return result.toISOString();
+  return String(result);
+}
+var import_faker, METHOD_ALIASES;
+var init_data_generator = __esm({
+  "src/engine/data-generator.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_faker = require("@faker-js/faker");
+    METHOD_ALIASES = {
+      "internet.userName": "username"
+    };
+  }
+});
+
+// src/utils/faker.ts
 function resolveFakeToken(tokenName) {
   switch (tokenName) {
     case "FAKE_FIRST_NAME":
-      return fakeFirstName();
+      return callFaker("person", "firstName");
     case "FAKE_LAST_NAME":
-      return fakeLastName();
+      return callFaker("person", "lastName");
     case "FAKE_AGE":
-      return fakeAge();
+      return String(Math.floor(Math.random() * 63) + 18);
+    // 18–80
     case "FAKE_EMAIL":
-      return fakeEmail();
+      return callFaker("internet", "email");
     case "FAKE_PHONE":
-      return fakePhone();
+      return callFaker("phone", "number");
     case "FAKE_PASSWORD":
-      return fakePassword();
-    default: {
-      const m = tokenName.match(/^FAKE_NUMBER_(\d+)$/);
-      if (m && m[1]) return fakeNumber(parseInt(m[1], 10));
-      return null;
+      return callFaker("internet", "password");
+  }
+  const numberMatch = tokenName.match(/^FAKE_NUMBER_(\d+)$/);
+  if (numberMatch && numberMatch[1]) {
+    const d = Math.max(1, parseInt(numberMatch[1], 10));
+    const min = d === 1 ? 0 : Math.pow(10, d - 1);
+    const max = Math.pow(10, d) - 1;
+    return String(Math.floor(Math.random() * (max - min + 1)) + min);
+  }
+  if (tokenName.startsWith("FAKE_")) {
+    const key = tokenName.slice(5);
+    const entry = GENERATOR_MAP[key];
+    if (entry) {
+      return callFaker(entry[0], entry[1]);
     }
   }
+  return null;
 }
-var FIRST_NAMES, LAST_NAMES, EMAIL_DOMAINS;
+var GENERATOR_MAP;
 var init_faker = __esm({
   "src/utils/faker.ts"() {
     "use strict";
     init_cjs_shims();
-    FIRST_NAMES = [
-      "Alice",
-      "Bob",
-      "Charlie",
-      "Diana",
-      "Eve",
-      "Frank",
-      "Grace",
-      "Henry",
-      "Iris",
-      "Jack",
-      "Kate",
-      "Liam",
-      "Mia",
-      "Noah",
-      "Olivia",
-      "Paul",
-      "Quinn",
-      "Rachel",
-      "Sam",
-      "Tara",
-      "Uma",
-      "Victor",
-      "Wendy",
-      "Xander",
-      "Yara",
-      "Zoe",
-      "Aaron",
-      "Bella",
-      "Carlos",
-      "Daisy",
-      "Ethan",
-      "Fiona"
-    ];
-    LAST_NAMES = [
-      "Smith",
-      "Johnson",
-      "Williams",
-      "Brown",
-      "Jones",
-      "Miller",
-      "Davis",
-      "Garcia",
-      "Wilson",
-      "Martinez",
-      "Anderson",
-      "Taylor",
-      "Thomas",
-      "Jackson",
-      "White",
-      "Harris",
-      "Martin",
-      "Thompson",
-      "Robinson",
-      "Clark",
-      "Lewis",
-      "Lee",
-      "Walker",
-      "Hall",
-      "Allen",
-      "Young",
-      "King",
-      "Wright"
-    ];
-    EMAIL_DOMAINS = ["example.com", "test.io", "mail.net", "demo.org", "qa.dev"];
+    init_data_generator();
+    GENERATOR_MAP = {};
+    for (const cat of getAvailableGenerators()) {
+      for (const m of cat.methods) {
+        const key = `${cat.category}_${m.name}`.toUpperCase();
+        GENERATOR_MAP[key] = [cat.category, m.name];
+      }
+    }
   }
 });
 
@@ -9571,6 +9771,259 @@ var init_data_loader = __esm({
   }
 });
 
+// src/storage/visual-regression-store.ts
+function configPath(rootDir) {
+  return import_path24.default.join(rootDir, ".assuremind", "visual-regression.json");
+}
+function diffSummaryPath(rootDir, runId) {
+  return import_path24.default.join(rootDir, "results", "visual-diffs", runId, "summary.json");
+}
+function diffRunsDir(rootDir) {
+  return import_path24.default.join(rootDir, "results", "visual-diffs");
+}
+function baselinesDir(rootDir) {
+  return import_path24.default.join(rootDir, "baselines");
+}
+async function readVisualConfig(rootDir) {
+  const fp = configPath(rootDir);
+  if (!await import_fs_extra20.default.pathExists(fp)) {
+    return { ...DEFAULT_CONFIG2 };
+  }
+  try {
+    const data = await readJson(fp);
+    return { ...DEFAULT_CONFIG2, ...data };
+  } catch {
+    return { ...DEFAULT_CONFIG2 };
+  }
+}
+async function writeVisualConfig(rootDir, config) {
+  await atomicWriteJson(configPath(rootDir), config);
+}
+async function saveDiffSummary(rootDir, summary) {
+  await atomicWriteJson(diffSummaryPath(rootDir, summary.runId), summary);
+}
+async function readDiffSummary(rootDir, runId) {
+  const data = await readJson(diffSummaryPath(rootDir, runId));
+  return data;
+}
+async function listDiffRuns(rootDir) {
+  const dir = diffRunsDir(rootDir);
+  if (!await import_fs_extra20.default.pathExists(dir)) return [];
+  const entries = await import_fs_extra20.default.readdir(dir, { withFileTypes: true });
+  const results = [];
+  for (const entry of entries) {
+    if (!entry.isDirectory()) continue;
+    const summaryFile = import_path24.default.join(dir, entry.name, "summary.json");
+    if (!await import_fs_extra20.default.pathExists(summaryFile)) continue;
+    try {
+      const data = await readJson(summaryFile);
+      const diffs = data.diffs ?? [];
+      results.push({
+        runId: data.runId,
+        timestamp: data.timestamp,
+        totalDiffs: diffs.length,
+        passed: diffs.filter((d) => d.status === "passed").length,
+        failed: diffs.filter((d) => d.status === "failed").length,
+        newCount: diffs.filter((d) => d.status === "new").length,
+        approved: diffs.filter((d) => d.status === "approved").length,
+        rejected: diffs.filter((d) => d.status === "rejected").length
+      });
+    } catch {
+    }
+  }
+  results.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+  return results;
+}
+async function updateDiffStatus(rootDir, runId, stepId, status) {
+  const summary = await readDiffSummary(rootDir, runId);
+  const entry = summary.diffs.find((d) => d.stepId === stepId);
+  if (!entry) {
+    throw new Error(`Diff entry not found for stepId "${stepId}" in run "${runId}"`);
+  }
+  entry.status = status;
+  await saveDiffSummary(rootDir, summary);
+  return summary;
+}
+async function approveAllDiffs(rootDir, runId) {
+  const summary = await readDiffSummary(rootDir, runId);
+  for (const entry of summary.diffs) {
+    if (entry.status === "failed" || entry.status === "new") {
+      entry.status = "approved";
+    }
+  }
+  await saveDiffSummary(rootDir, summary);
+  return summary;
+}
+async function listBaselines(rootDir) {
+  const dir = baselinesDir(rootDir);
+  if (!await import_fs_extra20.default.pathExists(dir)) return [];
+  const results = [];
+  async function walk(currentDir) {
+    const entries = await import_fs_extra20.default.readdir(currentDir, { withFileTypes: true });
+    for (const entry of entries) {
+      const fullPath = import_path24.default.join(currentDir, entry.name);
+      if (entry.isDirectory()) {
+        await walk(fullPath);
+      } else if (entry.name.endsWith(".png")) {
+        const relativePath = import_path24.default.relative(dir, fullPath).replace(/\\/g, "/");
+        const parts = relativePath.split("/");
+        const stat = await import_fs_extra20.default.stat(fullPath);
+        results.push({
+          path: fullPath,
+          relativePath,
+          suite: parts.length > 1 ? parts[0] : "",
+          caseName: parts.length > 2 ? parts[1] : "",
+          fileName: entry.name,
+          sizeBytes: stat.size
+        });
+      }
+    }
+  }
+  await walk(dir);
+  return results;
+}
+async function deleteBaseline(rootDir, baselinePath2) {
+  const dir = baselinesDir(rootDir);
+  const resolved = import_path24.default.resolve(baselinePath2);
+  if (!resolved.startsWith(import_path24.default.resolve(dir))) {
+    throw new Error("Path is outside baselines directory");
+  }
+  await import_fs_extra20.default.remove(resolved);
+}
+var import_path24, import_fs_extra20, DEFAULT_CONFIG2;
+var init_visual_regression_store = __esm({
+  "src/storage/visual-regression-store.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_path24 = __toESM(require("path"));
+    import_fs_extra20 = __toESM(require("fs-extra"));
+    init_utils();
+    DEFAULT_CONFIG2 = {
+      enabled: false,
+      defaultThreshold: 0.5,
+      fullPage: true,
+      maskSelectors: []
+    };
+  }
+});
+
+// src/engine/visual-comparator.ts
+async function readPng(filePath) {
+  const buffer = await import_fs_extra21.default.readFile(filePath);
+  return new Promise((resolve, reject) => {
+    const png = new import_pngjs.PNG();
+    png.parse(buffer, (err, data) => {
+      if (err) reject(err);
+      else resolve(data);
+    });
+  });
+}
+function encodePng(png) {
+  return import_pngjs.PNG.sync.write(png);
+}
+async function compareScreenshots(baselinePath2, actualPath, diffOutputPath, options = {}) {
+  const { threshold = 0.1, diffThreshold = 0.5 } = options;
+  const baselineExists = await import_fs_extra21.default.pathExists(baselinePath2);
+  if (!baselineExists) {
+    await import_fs_extra21.default.ensureDir(import_path25.default.dirname(baselinePath2));
+    await import_fs_extra21.default.copy(actualPath, baselinePath2);
+    return {
+      match: true,
+      diffPercentage: 0,
+      diffPixels: 0,
+      totalPixels: 0,
+      baselinePath: baselinePath2,
+      actualPath
+    };
+  }
+  const [baselinePng, actualPng] = await Promise.all([
+    readPng(baselinePath2),
+    readPng(actualPath)
+  ]);
+  if (baselinePng.width !== actualPng.width || baselinePng.height !== actualPng.height) {
+    await import_fs_extra21.default.ensureDir(import_path25.default.dirname(diffOutputPath));
+    const baseCopyPath2 = diffOutputPath.replace(/\.png$/, "-baseline.png");
+    const actualCopyPath2 = diffOutputPath.replace(/\.png$/, "-actual.png");
+    await Promise.all([
+      import_fs_extra21.default.copy(baselinePath2, baseCopyPath2),
+      import_fs_extra21.default.copy(actualPath, actualCopyPath2)
+    ]);
+    const totalPixels2 = Math.max(
+      baselinePng.width * baselinePng.height,
+      actualPng.width * actualPng.height
+    );
+    return {
+      match: false,
+      diffPercentage: 100,
+      diffPixels: totalPixels2,
+      totalPixels: totalPixels2,
+      baselinePath: baselinePath2,
+      actualPath,
+      error: `Size mismatch: baseline ${baselinePng.width}x${baselinePng.height} vs actual ${actualPng.width}x${actualPng.height}`
+    };
+  }
+  const { width, height } = baselinePng;
+  const diff = new import_pngjs.PNG({ width, height });
+  const diffPixels = (0, import_pixelmatch.default)(
+    baselinePng.data,
+    actualPng.data,
+    diff.data,
+    width,
+    height,
+    { threshold }
+  );
+  const totalPixels = width * height;
+  const diffPercentage = totalPixels > 0 ? diffPixels / totalPixels * 100 : 0;
+  const match = diffPercentage <= diffThreshold;
+  await import_fs_extra21.default.ensureDir(import_path25.default.dirname(diffOutputPath));
+  const diffBuffer = encodePng(diff);
+  const baseCopyPath = diffOutputPath.replace(/\.png$/, "-baseline.png");
+  const actualCopyPath = diffOutputPath.replace(/\.png$/, "-actual.png");
+  await Promise.all([
+    import_fs_extra21.default.writeFile(diffOutputPath, diffBuffer),
+    import_fs_extra21.default.copy(baselinePath2, baseCopyPath),
+    import_fs_extra21.default.copy(actualPath, actualCopyPath)
+  ]);
+  return {
+    match,
+    diffPercentage: Math.round(diffPercentage * 100) / 100,
+    diffPixels,
+    totalPixels,
+    diffImagePath: diffOutputPath,
+    baselinePath: baselinePath2,
+    actualPath
+  };
+}
+function getBaselinePath(rootDir, suiteSlug, caseSlug, stepId, browser, viewport) {
+  return import_path25.default.join(
+    rootDir,
+    "baselines",
+    suiteSlug,
+    caseSlug,
+    `${stepId}-${browser}-${viewport.width}x${viewport.height}.png`
+  );
+}
+function getDiffPath(rootDir, runId, stepId, browser, viewport) {
+  return import_path25.default.join(
+    rootDir,
+    "results",
+    "visual-diffs",
+    runId,
+    `${stepId}-${browser}-${viewport.width}x${viewport.height}-diff.png`
+  );
+}
+var import_pixelmatch, import_pngjs, import_fs_extra21, import_path25;
+var init_visual_comparator = __esm({
+  "src/engine/visual-comparator.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_pixelmatch = __toESM(require("pixelmatch"));
+    import_pngjs = require("pngjs");
+    import_fs_extra21 = __toESM(require("fs-extra"));
+    import_path25 = __toESM(require("path"));
+  }
+});
+
 // node_modules/escape-string-regexp/index.js
 var require_escape_string_regexp = __commonJS({
   "node_modules/escape-string-regexp/index.js"(exports2, module2) {
@@ -10705,11 +11158,11 @@ var require_is_docker = __commonJS({
   "node_modules/chrome-launcher/node_modules/is-docker/index.js"(exports2, module2) {
     "use strict";
     init_cjs_shims();
-    var fs30 = require("fs");
+    var fs34 = require("fs");
     var isDocker;
     function hasDockerEnv() {
       try {
-        fs30.statSync("/.dockerenv");
+        fs34.statSync("/.dockerenv");
         return true;
       } catch (_) {
         return false;
@@ -10717,7 +11170,7 @@ var require_is_docker = __commonJS({
     }
     function hasDockerCGroup() {
       try {
-        return fs30.readFileSync("/proc/self/cgroup", "utf8").includes("docker");
+        return fs34.readFileSync("/proc/self/cgroup", "utf8").includes("docker");
       } catch (_) {
         return false;
       }
@@ -10737,7 +11190,7 @@ var require_is_wsl = __commonJS({
     "use strict";
     init_cjs_shims();
     var os = require("os");
-    var fs30 = require("fs");
+    var fs34 = require("fs");
     var isDocker = require_is_docker();
     var isWsl3 = () => {
       if (process.platform !== "linux") {
@@ -10750,7 +11203,7 @@ var require_is_wsl = __commonJS({
         return true;
       }
       try {
-        return fs30.readFileSync("/proc/version", "utf8").toLowerCase().includes("microsoft") ? !isDocker() : false;
+        return fs34.readFileSync("/proc/version", "utf8").toLowerCase().includes("microsoft") ? !isDocker() : false;
       } catch (_) {
         return false;
       }
@@ -10811,15 +11264,15 @@ function toWSLPath(dir, fallback) {
     return fallback;
   }
 }
-function getLocalAppDataPath(path37) {
+function getLocalAppDataPath(path41) {
   const userRegExp = /\/mnt\/([a-z])\/Users\/([^\/:]+)\/AppData\//;
-  const results = userRegExp.exec(path37) || [];
+  const results = userRegExp.exec(path41) || [];
   return `/mnt/${results[1]}/Users/${results[2]}/AppData/Local`;
 }
-function getWSLLocalAppDataPath(path37) {
+function getWSLLocalAppDataPath(path41) {
   const userRegExp = /\/([a-z])\/Users\/([^\/:]+)\/AppData\//;
-  const results = userRegExp.exec(path37) || [];
-  return toWSLPath(`${results[1]}:\\Users\\${results[2]}\\AppData\\Local`, getLocalAppDataPath(path37));
+  const results = userRegExp.exec(path41) || [];
+  return toWSLPath(`${results[1]}:\\Users\\${results[2]}\\AppData\\Local`, getLocalAppDataPath(path41));
 }
 function makeUnixTmpDir() {
   return import_child_process3.default.execSync("mktemp -d -t lighthouse.XXXXXXX").toString().trim();
@@ -10827,16 +11280,16 @@ function makeUnixTmpDir() {
 function makeWin32TmpDir() {
   const winTmpPath = process.env.TEMP || process.env.TMP || (process.env.SystemRoot || process.env.windir) + "\\temp";
   const randomNumber = Math.floor(Math.random() * 9e7 + 1e7);
-  const tmpdir = (0, import_path24.join)(winTmpPath, "lighthouse." + randomNumber);
+  const tmpdir = (0, import_path26.join)(winTmpPath, "lighthouse." + randomNumber);
   (0, import_fs.mkdirSync)(tmpdir, { recursive: true });
   return tmpdir;
 }
-var import_path24, import_child_process3, import_fs, import_is_wsl, LauncherError, ChromePathNotSetError, InvalidUserDataDirectoryError, UnsupportedPlatformError, ChromeNotInstalledError;
+var import_path26, import_child_process3, import_fs, import_is_wsl, LauncherError, ChromePathNotSetError, InvalidUserDataDirectoryError, UnsupportedPlatformError, ChromeNotInstalledError;
 var init_utils3 = __esm({
   "node_modules/chrome-launcher/dist/utils.js"() {
     "use strict";
     init_cjs_shims();
-    import_path24 = require("path");
+    import_path26 = require("path");
     import_child_process3 = __toESM(require("child_process"), 1);
     import_fs = require("fs");
     import_is_wsl = __toESM(require_is_wsl(), 1);
@@ -10912,7 +11365,7 @@ function darwin() {
   }
   (0, import_child_process4.execSync)(`${LSREGISTER} -dump | grep -i 'google chrome\\( canary\\)\\?\\.app' | awk '{$1=""; print $0}'`).toString().split(newLineRegex).forEach((inst) => {
     suffixes.forEach((suffix) => {
-      const execPath = import_path25.default.join(inst.substring(0, inst.indexOf(".app") + 4).trim(), suffix);
+      const execPath = import_path27.default.join(inst.substring(0, inst.indexOf(".app") + 4).trim(), suffix);
       if (canAccess(execPath) && installations.indexOf(execPath) === -1) {
         installations.push(execPath);
       }
@@ -10952,7 +11405,7 @@ function linux() {
     installations.push(customChromePath);
   }
   const desktopInstallationFolders = [
-    import_path25.default.join((0, import_os.homedir)(), ".local/share/applications/"),
+    import_path27.default.join((0, import_os.homedir)(), ".local/share/applications/"),
     "/usr/share/applications/"
   ];
   desktopInstallationFolders.forEach((folder) => {
@@ -11000,8 +11453,8 @@ function wsl() {
 function win32() {
   const installations = [];
   const suffixes = [
-    `${import_path25.default.sep}Google${import_path25.default.sep}Chrome SxS${import_path25.default.sep}Application${import_path25.default.sep}chrome.exe`,
-    `${import_path25.default.sep}Google${import_path25.default.sep}Chrome${import_path25.default.sep}Application${import_path25.default.sep}chrome.exe`
+    `${import_path27.default.sep}Google${import_path27.default.sep}Chrome SxS${import_path27.default.sep}Application${import_path27.default.sep}chrome.exe`,
+    `${import_path27.default.sep}Google${import_path27.default.sep}Chrome${import_path27.default.sep}Application${import_path27.default.sep}chrome.exe`
   ];
   const prefixes = [
     process.env.LOCALAPPDATA,
@@ -11013,7 +11466,7 @@ function win32() {
     installations.push(customChromePath);
   }
   prefixes.forEach((prefix) => suffixes.forEach((suffix) => {
-    const chromePath = import_path25.default.join(prefix, suffix);
+    const chromePath = import_path27.default.join(prefix, suffix);
     if (canAccess(chromePath)) {
       installations.push(chromePath);
     }
@@ -11061,13 +11514,13 @@ function findChromeExecutables(folder) {
   }
   return installations;
 }
-var import_fs2, import_path25, import_os, import_child_process4, import_escape_string_regexp, newLineRegex;
+var import_fs2, import_path27, import_os, import_child_process4, import_escape_string_regexp, newLineRegex;
 var init_chrome_finder = __esm({
   "node_modules/chrome-launcher/dist/chrome-finder.js"() {
     "use strict";
     init_cjs_shims();
     import_fs2 = __toESM(require("fs"), 1);
-    import_path25 = __toESM(require("path"), 1);
+    import_path27 = __toESM(require("path"), 1);
     import_os = require("os");
     import_child_process4 = require("child_process");
     import_escape_string_regexp = __toESM(require_escape_string_regexp(), 1);
@@ -11219,12 +11672,12 @@ function killAll() {
   }
   return errors;
 }
-var fs18, net, import_child_process5, isWsl2, isWindows3, _SIGINT, _SIGINT_EXIT_CODE, _SUPPORTED_PLATFORMS, instances, sigintListener, Launcher;
+var fs20, net, import_child_process5, isWsl2, isWindows3, _SIGINT, _SIGINT_EXIT_CODE, _SUPPORTED_PLATFORMS, instances, sigintListener, Launcher;
 var init_chrome_launcher = __esm({
   "node_modules/chrome-launcher/dist/chrome-launcher.js"() {
     "use strict";
     init_cjs_shims();
-    fs18 = __toESM(require("fs"), 1);
+    fs20 = __toESM(require("fs"), 1);
     net = __toESM(require("net"), 1);
     init_chrome_finder();
     init_random_port();
@@ -11247,7 +11700,7 @@ var init_chrome_launcher = __esm({
         this.opts = opts;
         this.tmpDirandPidFileReady = false;
         this.remoteDebuggingPipes = null;
-        this.fs = moduleOverrides.fs || fs18;
+        this.fs = moduleOverrides.fs || fs20;
         this.spawn = moduleOverrides.spawn || import_child_process5.spawn;
         lighthouse_logger_default.setLevel(defaults(this.opts.logLevel, "silent"));
         this.startingUrl = defaults(this.opts.startingUrl, "about:blank");
@@ -11525,7 +11978,9 @@ var init_dist = __esm({
 // src/engine/runner.ts
 var runner_exports = {};
 __export(runner_exports, {
-  runTests: () => runTests
+  getActiveRunId: () => getActiveRunId,
+  runTests: () => runTests,
+  stopActiveRun: () => stopActiveRun
 });
 function isCaseApiOnly(tc) {
   if (tc.steps.length === 0) return false;
@@ -11537,10 +11992,24 @@ function isSuiteApiOnly(suite) {
 function isSuiteAudit(suite) {
   return suite.type === "audit" || suite.type === "performance";
 }
+function stopActiveRun() {
+  if (_activeRunAbort) {
+    _activeRunAbort();
+  }
+}
+function getActiveRunId() {
+  return _activeRunId;
+}
 async function runTests(rootDir, runConfig, autotestConfig, ws) {
   const runId = (0, import_crypto10.randomUUID)();
   const startedAt = (/* @__PURE__ */ new Date()).toISOString();
-  const testsDir = import_path26.default.join(rootDir, "tests");
+  const testsDir = import_path28.default.join(rootDir, "tests");
+  let _runStopped = false;
+  _activeRunId = runId;
+  _activeRunAbort = () => {
+    _runStopped = true;
+    logger31.info({ runId }, "Run stop requested");
+  };
   const activeEnv = autotestConfig.environment ?? "dev";
   const envUrl = autotestConfig.environmentUrls?.[activeEnv];
   if (envUrl) {
@@ -11557,6 +12026,14 @@ async function runTests(rootDir, runConfig, autotestConfig, ws) {
   const browserManager = new BrowserManager();
   const healingReporter = new HealingReporter();
   const allureReporter = new AllureReporter(rootDir, runId, activeEnv);
+  const visualConfig = await readVisualConfig(rootDir);
+  const visualDiffEntries = [];
+  if (visualConfig.enabled) {
+    if (autotestConfig.screenshot !== "on") {
+      autotestConfig = { ...autotestConfig, screenshot: "on" };
+    }
+    logToFile("info", "Visual regression enabled \u2014 screenshots forced ON", { threshold: visualConfig.defaultThreshold, fullPage: visualConfig.fullPage });
+  }
   try {
     const pairs = await collectWork(testsDir, runConfig);
     if (pairs.length === 0) {
@@ -11663,6 +12140,9 @@ async function runTests(rootDir, runConfig, autotestConfig, ws) {
       allPairs,
       autotestConfig.parallel,
       async ({ browserName, browser, suite, testCase, dataRow, dataRowIndex }) => {
+        if (_runStopped) {
+          return null;
+        }
         const caseVariables = dataRow ? { ...variables, ...dataRow } : variables;
         const caseName = dataRow ? `${testCase.name} [row ${(dataRowIndex ?? 0) + 1}]` : testCase.name;
         ws?.broadcast("run:case", {
@@ -11692,7 +12172,9 @@ async function runTests(rootDir, runConfig, autotestConfig, ws) {
           ws,
           logToFile,
           compositeCaseId,
-          ragManager
+          ragManager,
+          visualConfig,
+          visualDiffEntries
         );
         result.suiteType = suite.type;
         if (dataRow !== void 0) {
@@ -11715,14 +12197,15 @@ async function runTests(rootDir, runConfig, autotestConfig, ws) {
         return { ...result, browserName };
       }
     );
+    const validCaseResults = allCaseResults.filter(Boolean);
     if (browsers.length > 1) {
       for (const browserName of browsers) {
-        const browserResults = allCaseResults.filter((r) => r.browserName === browserName);
+        const browserResults = validCaseResults.filter((r) => r.browserName === browserName);
         const grouped = groupBySuite(browserResults, browserName);
         allSuiteResults.push(...grouped);
       }
     } else {
-      const grouped = groupBySuite(allCaseResults);
+      const grouped = groupBySuite(validCaseResults);
       allSuiteResults.push(...grouped);
     }
     const finishedAt = (/* @__PURE__ */ new Date()).toISOString();
@@ -11742,9 +12225,21 @@ async function runTests(rootDir, runConfig, autotestConfig, ws) {
       generateAllureReport(rootDir, runId).catch(() => void 0);
     }
     if (autotestConfig.reporting.json) {
-      const jsonPath = import_path26.default.join(rootDir, "results", `run-${runId}.json`);
-      await import_fs_extra20.default.ensureDir(import_path26.default.dirname(jsonPath));
-      await import_fs_extra20.default.writeJson(jsonPath, runResult, { spaces: 2 });
+      const jsonPath = import_path28.default.join(rootDir, "results", `run-${runId}.json`);
+      await import_fs_extra22.default.ensureDir(import_path28.default.dirname(jsonPath));
+      await import_fs_extra22.default.writeJson(jsonPath, runResult, { spaces: 2 });
+    }
+    if (visualConfig.enabled && visualDiffEntries.length > 0) {
+      await saveDiffSummary(rootDir, {
+        runId,
+        timestamp: finishedAt,
+        diffs: visualDiffEntries
+      });
+      logToFile("info", `Visual regression: ${visualDiffEntries.length} comparisons saved`, {
+        passed: visualDiffEntries.filter((d) => d.status === "passed").length,
+        failed: visualDiffEntries.filter((d) => d.status === "failed").length,
+        new: visualDiffEntries.filter((d) => d.status === "new").length
+      });
     }
     await healingReporter.flush(rootDir, runId);
     await smartRouter.getCache().persist();
@@ -11768,17 +12263,22 @@ async function runTests(rootDir, runConfig, autotestConfig, ws) {
     );
     return runResult;
   } finally {
+    _activeRunAbort = null;
+    _activeRunId = null;
     await browserManager.closeAll();
+    if (_runStopped) {
+      ws?.broadcast("run:stopped", { runId });
+    }
   }
 }
-async function runCase(rootDir, runId, suite, testCase, browserName, browser, config, variables, sharedVariables, provider, budget, healingReporter, browserManager, ws, logToFile, wsCaseId, ragManager) {
+async function runCase(rootDir, runId, suite, testCase, browserName, browser, config, variables, sharedVariables, provider, budget, healingReporter, browserManager, ws, logToFile, wsCaseId, ragManager, visualConfig, visualDiffEntries) {
   const broadcastCaseId = wsCaseId ?? testCase.id;
   const caseStart = (/* @__PURE__ */ new Date()).toISOString();
   const stepResults = [];
   const previousSteps = [];
   const apiOnly = isSuiteApiOnly(suite) || isCaseApiOnly(testCase);
   const caseConfig = isSuiteAudit(suite) ? { ...config, screenshot: "off", video: "off", trace: "off" } : config;
-  const tracePath = !apiOnly && caseConfig.trace !== "off" ? import_path26.default.join(rootDir, "results", "traces", `${runId}_${testCase.id}_${browserName}.zip`) : void 0;
+  const tracePath = !apiOnly && caseConfig.trace !== "off" ? import_path28.default.join(rootDir, "results", "traces", `${runId}_${testCase.id}_${browserName}.zip`) : void 0;
   let context = null;
   let page;
   if (apiOnly) {
@@ -11786,7 +12286,7 @@ async function runCase(rootDir, runId, suite, testCase, browserName, browser, co
     logger31.debug({ caseName: testCase.name }, "API-only case \u2014 zero browser, using standalone HTTP client");
   } else {
     if (!browser) throw new Error("Browser required for UI test cases");
-    context = await browserManager.newContext(browser, caseConfig, import_path26.default.join(rootDir, "results", "videos"));
+    context = await browserManager.newContext(browser, caseConfig, import_path28.default.join(rootDir, "results", "videos"));
     page = await browserManager.newPage(context);
     await installHighlighter(page);
   }
@@ -11895,6 +12395,40 @@ async function runCase(rootDir, runId, suite, testCase, browserName, browser, co
         ...result.healed ? { healed: true } : {}
       });
       stepResults.push(result);
+      if (visualConfig?.enabled && visualDiffEntries && !apiOnly && step.visualCheck && result.status === "passed" && result.screenshotPath) {
+        try {
+          const viewport = config.viewport ?? { width: 1280, height: 720 };
+          const suiteSlug = toSlug(suite.name);
+          const caseSlug = toSlug(testCase.name);
+          const bPath = getBaselinePath(rootDir, suiteSlug, caseSlug, step.id, browserName, viewport);
+          const dPath = getDiffPath(rootDir, runId, step.id, browserName, viewport);
+          const cmpResult = await compareScreenshots(bPath, result.screenshotPath, dPath, {
+            threshold: 0.1,
+            diffThreshold: visualConfig.defaultThreshold
+          });
+          const entryStatus = cmpResult.totalPixels === 0 ? "new" : cmpResult.match ? "passed" : "failed";
+          visualDiffEntries.push({
+            stepId: step.id,
+            caseId: testCase.id,
+            caseName: testCase.name,
+            suiteName: suite.name,
+            suiteId: suite.id,
+            browser: browserName,
+            viewport: `${viewport.width}x${viewport.height}`,
+            diffPercentage: cmpResult.diffPercentage,
+            threshold: visualConfig.defaultThreshold,
+            status: entryStatus,
+            baselinePath: cmpResult.baselinePath,
+            actualPath: cmpResult.actualPath,
+            diffPath: cmpResult.diffImagePath ?? dPath
+          });
+          logToFile?.("info", `  Visual: ${step.id} \u2014 ${entryStatus} (diff: ${cmpResult.diffPercentage}%)`, {
+            baseline: bPath
+          });
+        } catch (vrErr) {
+          logger31.debug({ err: vrErr, stepId: step.id }, "Visual regression comparison failed");
+        }
+      }
       if (result.status === "passed") {
         previousSteps.push({ instruction: step.instruction, code: result.code });
       } else if (result.status === "failed") {
@@ -11921,16 +12455,16 @@ async function runCase(rootDir, runId, suite, testCase, browserName, browser, co
           const launch2 = chromeLauncher.launch ?? chromeLauncher.default?.launch;
           const { chromium: pwChromium } = await import("playwright");
           const chromePath = pwChromium.executablePath();
-          const lhBaseDir = import_path26.default.join(rootDir, "results", ".lh-profiles");
-          await import_fs_extra20.default.ensureDir(lhBaseDir);
+          const lhBaseDir = import_path28.default.join(rootDir, "results", ".lh-profiles");
+          await import_fs_extra22.default.ensureDir(lhBaseDir);
           for (let auditIdx = 0; auditIdx < navigatedSteps.length; auditIdx++) {
             const { s, idx } = navigatedSteps[auditIdx];
             const url = s.auditUrl ?? s.navigatedToUrl;
             logToFile?.("info", `  Auditing: ${url}`);
             let chromeInstance = null;
-            const userDataDir = import_path26.default.join(lhBaseDir, `audit-${Date.now()}-${auditIdx}`);
+            const userDataDir = import_path28.default.join(lhBaseDir, `audit-${Date.now()}-${auditIdx}`);
             try {
-              await import_fs_extra20.default.ensureDir(userDataDir);
+              await import_fs_extra22.default.ensureDir(userDataDir);
               chromeInstance = await launch2({
                 chromePath,
                 chromeFlags: ["--headless", "--no-sandbox", "--disable-gpu"],
@@ -12020,7 +12554,7 @@ async function runCase(rootDir, runId, suite, testCase, browserName, browser, co
               } catch {
               }
               try {
-                await import_fs_extra20.default.remove(userDataDir);
+                await import_fs_extra22.default.remove(userDataDir);
               } catch {
               }
             }
@@ -12073,11 +12607,11 @@ async function runCase(rootDir, runId, suite, testCase, browserName, browser, co
       await browserManager.closeContext(context, caseConfig, tracePath);
       const videoDeleteOnPass = caseConfig.video === "retain-on-failure" || caseConfig.video === "on-first-retry";
       if (videoDeleteOnPass && caseStatus === "passed" && pendingVideoPath) {
-        await import_fs_extra20.default.remove(pendingVideoPath).catch(() => void 0);
+        await import_fs_extra22.default.remove(pendingVideoPath).catch(() => void 0);
       }
       const traceDeleteOnPass = caseConfig.trace === "retain-on-failure" || caseConfig.trace === "on-first-retry";
       if (traceDeleteOnPass && caseStatus === "passed" && tracePath) {
-        await import_fs_extra20.default.remove(tracePath).catch(() => void 0);
+        await import_fs_extra22.default.remove(tracePath).catch(() => void 0);
       }
     }
   }
@@ -12219,14 +12753,14 @@ function buildRunResult(runId, startedAt, finishedAt, suites, environment) {
     skipped
   };
 }
-var import_path26, import_crypto10, import_fs_extra20, logger31;
+var import_path28, import_crypto10, import_fs_extra22, logger31, _activeRunAbort, _activeRunId;
 var init_runner = __esm({
   "src/engine/runner.ts"() {
     "use strict";
     init_cjs_shims();
-    import_path26 = __toESM(require("path"));
+    import_path28 = __toESM(require("path"));
     import_crypto10 = require("crypto");
-    import_fs_extra20 = __toESM(require("fs-extra"));
+    import_fs_extra22 = __toESM(require("fs-extra"));
     init_suite_store();
     init_case_store();
     init_variable_store();
@@ -12244,8 +12778,13 @@ var init_runner = __esm({
     init_highlighter();
     init_data_loader();
     init_step_type_detector();
+    init_visual_regression_store();
+    init_visual_comparator();
+    init_sanitize();
     init_logger();
     logger31 = createChildLogger("runner");
+    _activeRunAbort = null;
+    _activeRunId = null;
   }
 });
 
@@ -12300,6 +12839,10 @@ async function runRoutes(fastify) {
       return sendError(reply, 500, "Failed to start run", err);
     }
   });
+  fastify.post("/run/stop", async (_req, reply) => {
+    stopActiveRun();
+    return reply.status(202).send({ status: "stopping" });
+  });
   fastify.get("/run", async (req, reply) => {
     const parsed = ListRunsQuery.safeParse(req.query);
     if (!parsed.success) {
@@ -12739,7 +13282,7 @@ async function storyRoutes(fastify) {
       return reply.status(400).send({ error: "Invalid request", details: parsed.error.issues });
     }
     try {
-      const testsDir = import_path27.default.join(rootDir, "tests");
+      const testsDir = import_path29.default.join(rootDir, "tests");
       let storyText = parsed.data.story;
       if (parsed.data.jiraUrl) {
         const issueKey = extractIssueKey(parsed.data.jiraUrl);
@@ -12785,7 +13328,7 @@ async function storyRoutes(fastify) {
       return reply.status(400).send({ error: "Invalid request", details: parsed.error.issues });
     }
     const { stories, concurrency } = parsed.data;
-    const testsDir = import_path27.default.join(rootDir, "tests");
+    const testsDir = import_path29.default.join(rootDir, "tests");
     const wsManager = fastify.wsManager;
     logger34.info({ total: stories.length, concurrency }, "Bulk story generation requested");
     const enrichedStories = await Promise.all(
@@ -12897,7 +13440,7 @@ async function storyRoutes(fastify) {
       }
       const storyText = storyLines.join("\n");
       const suiteName = parsed.data.suiteName ?? `${spec.title} API Tests`;
-      const testsDir = import_path27.default.join(rootDir, "tests");
+      const testsDir = import_path29.default.join(rootDir, "tests");
       const { suiteId } = await generateSuiteFromStory(storyText, {
         rootDir,
         outputDir: testsDir,
@@ -12917,12 +13460,12 @@ async function storyRoutes(fastify) {
     }
   });
 }
-var import_path27, import_zod15, logger34, GenerateStoryBody, FetchJiraBody;
+var import_path29, import_zod15, logger34, GenerateStoryBody, FetchJiraBody;
 var init_story = __esm({
   "src/server/routes/story.ts"() {
     "use strict";
     init_cjs_shims();
-    import_path27 = __toESM(require("path"));
+    import_path29 = __toESM(require("path"));
     import_zod15 = require("zod");
     init_router();
     init_swagger_parser();
@@ -12993,27 +13536,27 @@ var init_report = __esm({
 });
 
 // src/storage/baseline-store.ts
-function baselinesDir(rootDir) {
-  return import_path28.default.join(rootDir, "results", "baselines");
+function baselinesDir2(rootDir) {
+  return import_path30.default.join(rootDir, "results", "baselines");
 }
 function baselinePath(rootDir, stepId) {
-  return import_path28.default.join(baselinesDir(rootDir), `${stepId}.png`);
+  return import_path30.default.join(baselinesDir2(rootDir), `${stepId}.png`);
 }
 async function saveBaseline(rootDir, stepId, sourcePath) {
-  const dir = baselinesDir(rootDir);
-  await import_fs_extra21.default.ensureDir(dir);
-  await import_fs_extra21.default.copy(sourcePath, baselinePath(rootDir, stepId), { overwrite: true });
+  const dir = baselinesDir2(rootDir);
+  await import_fs_extra23.default.ensureDir(dir);
+  await import_fs_extra23.default.copy(sourcePath, baselinePath(rootDir, stepId), { overwrite: true });
 }
 async function hasBaseline(rootDir, stepId) {
-  return import_fs_extra21.default.pathExists(baselinePath(rootDir, stepId));
+  return import_fs_extra23.default.pathExists(baselinePath(rootDir, stepId));
 }
-var import_path28, import_fs_extra21;
+var import_path30, import_fs_extra23;
 var init_baseline_store = __esm({
   "src/storage/baseline-store.ts"() {
     "use strict";
     init_cjs_shims();
-    import_path28 = __toESM(require("path"));
-    import_fs_extra21 = __toESM(require("fs-extra"));
+    import_path30 = __toESM(require("path"));
+    import_fs_extra23 = __toESM(require("fs-extra"));
   }
 });
 
@@ -13024,26 +13567,26 @@ async function mediaRoutes(fastify) {
     if (!["screenshots", "videos", "traces", "logs", "baselines"].includes(category)) {
       return reply.status(404).send({ error: "Unknown media category" });
     }
-    const safeName = import_path29.default.basename(filename);
-    const filePath = import_path29.default.join(fastify.rootDir, "results", category, safeName);
-    if (!await import_fs_extra22.default.pathExists(filePath)) {
+    const safeName = import_path31.default.basename(filename);
+    const filePath = import_path31.default.join(fastify.rootDir, "results", category, safeName);
+    if (!await import_fs_extra24.default.pathExists(filePath)) {
       return reply.status(404).send({ error: `File not found: ${safeName}` });
     }
-    const ext = import_path29.default.extname(safeName).toLowerCase();
+    const ext = import_path31.default.extname(safeName).toLowerCase();
     const mimeType = MIME[ext] ?? "application/octet-stream";
     if (ext === ".zip") {
       void reply.header("Content-Disposition", `attachment; filename="${safeName}"`);
     }
-    const stat = await import_fs_extra22.default.stat(filePath);
+    const stat = await import_fs_extra24.default.stat(filePath);
     void reply.header("Content-Length", stat.size);
-    return reply.type(mimeType).send(import_fs_extra22.default.createReadStream(filePath));
+    return reply.type(mimeType).send(import_fs_extra24.default.createReadStream(filePath));
   });
   fastify.post("/baselines/:stepId/capture", async (req, reply) => {
     try {
       const body = req.body;
       if (!body?.screenshotPath) return reply.status(400).send({ error: "screenshotPath required" });
-      const fullPath = import_path29.default.isAbsolute(body.screenshotPath) ? body.screenshotPath : import_path29.default.join(fastify.rootDir, body.screenshotPath);
-      if (!await import_fs_extra22.default.pathExists(fullPath)) return reply.status(404).send({ error: "Screenshot not found" });
+      const fullPath = import_path31.default.isAbsolute(body.screenshotPath) ? body.screenshotPath : import_path31.default.join(fastify.rootDir, body.screenshotPath);
+      if (!await import_fs_extra24.default.pathExists(fullPath)) return reply.status(404).send({ error: "Screenshot not found" });
       await saveBaseline(fastify.rootDir, req.params.stepId, fullPath);
       return reply.send({ saved: true });
     } catch (err) {
@@ -13054,21 +13597,21 @@ async function mediaRoutes(fastify) {
     try {
       const exists = await hasBaseline(fastify.rootDir, req.params.stepId);
       if (!exists) return reply.send({ hasBaseline: false });
-      const filePath = import_path29.default.join(fastify.rootDir, "results", "baselines", `${req.params.stepId}.png`);
-      const stat = await import_fs_extra22.default.stat(filePath).catch(() => null);
+      const filePath = import_path31.default.join(fastify.rootDir, "results", "baselines", `${req.params.stepId}.png`);
+      const stat = await import_fs_extra24.default.stat(filePath).catch(() => null);
       return reply.send({ hasBaseline: true, capturedAt: stat?.mtimeMs ?? Date.now() });
     } catch (err) {
       return sendError(reply, 500, "Failed to check baseline", err);
     }
   });
 }
-var import_path29, import_fs_extra22, MIME;
+var import_path31, import_fs_extra24, MIME;
 var init_media = __esm({
   "src/server/routes/media.ts"() {
     "use strict";
     init_cjs_shims();
-    import_path29 = __toESM(require("path"));
-    import_fs_extra22 = __toESM(require("fs-extra"));
+    import_path31 = __toESM(require("path"));
+    import_fs_extra24 = __toESM(require("fs-extra"));
     init_baseline_store();
     init_utils2();
     MIME = {
@@ -13112,8 +13655,8 @@ var init_client = __esm({
         this.authHeader = "Basic " + Buffer.from(`${config.jiraEmail}:${config.jiraApiToken}`).toString("base64");
       }
       // ─── Jira REST API helpers ──────────────────────────────────────────────────
-      async jiraRequest(method, path37, body) {
-        const url = `${this.config.jiraBaseUrl}/rest/api/3${path37}`;
+      async jiraRequest(method, path41, body) {
+        const url = `${this.config.jiraBaseUrl}/rest/api/3${path41}`;
         logger36.debug({ method, url }, "Jira API request");
         const headers = {
           "Authorization": this.authHeader,
@@ -13130,7 +13673,7 @@ var init_client = __esm({
         if (!res.ok) {
           const text = await res.text();
           logger36.error({ status: res.status, url, body: text }, "Jira API error");
-          throw new Error(`Jira API ${method} ${path37} \u2192 ${res.status}: ${text}`);
+          throw new Error(`Jira API ${method} ${path41} \u2192 ${res.status}: ${text}`);
         }
         if (res.status === 204) return void 0;
         return res.json();
@@ -13157,10 +13700,10 @@ var init_client = __esm({
         return this.xrayToken;
       }
       // ─── Xray API helpers ─────────────────────────────────────────────────────
-      async xrayRequest(method, path37, body) {
+      async xrayRequest(method, path41, body) {
         const token = await this.getXrayToken();
         const baseUrl = token ? "https://xray.cloud.getxray.app/api/v2" : `${this.config.jiraBaseUrl}/rest/raven/2.0/api`;
-        const url = `${baseUrl}${path37}`;
+        const url = `${baseUrl}${path41}`;
         logger36.debug({ method, url }, "Xray API request");
         const headers = {
           "Accept": "application/json"
@@ -13181,7 +13724,7 @@ var init_client = __esm({
         if (!res.ok) {
           const text = await res.text();
           logger36.error({ status: res.status, url, body: text }, "Xray API error");
-          throw new Error(`Xray API ${method} ${path37} \u2192 ${res.status}: ${text}`);
+          throw new Error(`Xray API ${method} ${path41} \u2192 ${res.status}: ${text}`);
         }
         if (res.status === 204) return void 0;
         return res.json();
@@ -13768,11 +14311,11 @@ var init_xray = __esm({
 
 // src/storage/xray-store.ts
 function mappingPath(rootDir) {
-  return import_path30.default.join(rootDir, "assuremind-data", MAPPING_FILE);
+  return import_path32.default.join(rootDir, "assuremind-data", MAPPING_FILE);
 }
 async function readXrayMapping(rootDir) {
   const filePath = mappingPath(rootDir);
-  if (!await import_fs_extra23.default.pathExists(filePath)) {
+  if (!await import_fs_extra25.default.pathExists(filePath)) {
     return {
       projectKey: "",
       suites: [],
@@ -13789,7 +14332,7 @@ async function readXrayMapping(rootDir) {
 }
 async function writeXrayMapping(rootDir, mapping) {
   const filePath = mappingPath(rootDir);
-  await import_fs_extra23.default.ensureDir(import_path30.default.dirname(filePath));
+  await import_fs_extra25.default.ensureDir(import_path32.default.dirname(filePath));
   const data = { ...mapping, updatedAt: (/* @__PURE__ */ new Date()).toISOString() };
   await atomicWriteJson(filePath, data);
   logger37.debug({ path: filePath }, "Xray mapping written");
@@ -13824,13 +14367,13 @@ function upsertCaseMapping(suiteMapping, caseMapping) {
   }
   return { ...suiteMapping, cases };
 }
-var import_path30, import_fs_extra23, logger37, MAPPING_FILE;
+var import_path32, import_fs_extra25, logger37, MAPPING_FILE;
 var init_xray_store = __esm({
   "src/storage/xray-store.ts"() {
     "use strict";
     init_cjs_shims();
-    import_path30 = __toESM(require("path"));
-    import_fs_extra23 = __toESM(require("fs-extra"));
+    import_path32 = __toESM(require("path"));
+    import_fs_extra25 = __toESM(require("fs-extra"));
     init_xray();
     init_utils();
     init_logger();
@@ -14565,14 +15108,14 @@ var init_xray2 = __esm({
 });
 
 // src/git/service.ts
-var import_simple_git, import_fs_extra24, import_path31, logger40, GitService;
+var import_simple_git, import_fs_extra26, import_path33, logger40, GitService;
 var init_service2 = __esm({
   "src/git/service.ts"() {
     "use strict";
     init_cjs_shims();
     import_simple_git = __toESM(require("simple-git"));
-    import_fs_extra24 = __toESM(require("fs-extra"));
-    import_path31 = __toESM(require("path"));
+    import_fs_extra26 = __toESM(require("fs-extra"));
+    import_path33 = __toESM(require("path"));
     init_logger();
     logger40 = createChildLogger("git-service");
     GitService = class {
@@ -14772,8 +15315,8 @@ var init_service2 = __esm({
         return status.conflicted;
       }
       async getFileConflictContent(filePath) {
-        const fullPath = import_path31.default.join(this.rootDir, filePath);
-        const content = await import_fs_extra24.default.readFile(fullPath, "utf-8");
+        const fullPath = import_path33.default.join(this.rootDir, filePath);
+        const content = await import_fs_extra26.default.readFile(fullPath, "utf-8");
         let ours = "";
         let theirs = "";
         let section = "none";
@@ -14799,8 +15342,8 @@ var init_service2 = __esm({
         return { ours: ours.trimEnd(), theirs: theirs.trimEnd() };
       }
       async resolveConflict(filePath, resolvedContent) {
-        const fullPath = import_path31.default.join(this.rootDir, filePath);
-        await import_fs_extra24.default.writeFile(fullPath, resolvedContent, "utf-8");
+        const fullPath = import_path33.default.join(this.rootDir, filePath);
+        await import_fs_extra26.default.writeFile(fullPath, resolvedContent, "utf-8");
         await this.git.add(filePath);
         logger40.info({ filePath }, "Conflict resolved");
       }
@@ -15114,7 +15657,7 @@ async function gitRoutes(fastify) {
       const changedFiles = stdout.split("\n").filter(Boolean);
       const { listSuiteDirs: listSuiteDirs2, readSuite: readSuite2 } = await Promise.resolve().then(() => (init_suite_store(), suite_store_exports));
       const { listCases: listCases2 } = await Promise.resolve().then(() => (init_case_store(), case_store_exports));
-      const testsDir = import_path32.default.join(rootDir, "tests");
+      const testsDir = import_path34.default.join(rootDir, "tests");
       const suiteDirs = await listSuiteDirs2(testsDir);
       const impacted = [];
       for (const suiteDir of suiteDirs) {
@@ -15124,8 +15667,8 @@ async function gitRoutes(fastify) {
           for (const tc of cases) {
             const allText = [tc.name, tc.description ?? "", ...tc.steps.map((s) => s.instruction)].join(" ").toLowerCase();
             for (const file of changedFiles) {
-              const basename = import_path32.default.basename(file).toLowerCase();
-              const dirname = import_path32.default.dirname(file).toLowerCase();
+              const basename = import_path34.default.basename(file).toLowerCase();
+              const dirname = import_path34.default.dirname(file).toLowerCase();
               if (allText.includes(basename) || allText.includes(dirname)) {
                 impacted.push({ caseId: tc.id, caseName: tc.name, suiteId: suite.id, suiteName: suite.name, reason: `Mentions "${file}"` });
                 break;
@@ -15141,12 +15684,12 @@ async function gitRoutes(fastify) {
     }
   });
 }
-var import_path32, import_zod18, logger42, CheckoutBody, CommitBody, PullBody, FullSyncBody, ResolveConflictBody, ResolveConflictAIBody;
+var import_path34, import_zod18, logger42, CheckoutBody, CommitBody, PullBody, FullSyncBody, ResolveConflictBody, ResolveConflictAIBody;
 var init_git = __esm({
   "src/server/routes/git.ts"() {
     "use strict";
     init_cjs_shims();
-    import_path32 = __toESM(require("path"));
+    import_path34 = __toESM(require("path"));
     import_zod18 = require("zod");
     init_service2();
     init_ai();
@@ -15197,12 +15740,12 @@ function parseCSV(content) {
 }
 async function dataFileRoutes(fastify) {
   const rootDir = fastify.rootDir;
-  const dataDir = import_path33.default.join(rootDir, "tests", "data");
-  await import_fs_extra25.default.ensureDir(dataDir);
+  const dataDir = import_path35.default.join(rootDir, "tests", "data");
+  await import_fs_extra27.default.ensureDir(dataDir);
   fastify.get("/data-files", async (_req, reply) => {
     try {
-      await import_fs_extra25.default.ensureDir(dataDir);
-      const entries = await import_fs_extra25.default.readdir(dataDir, { withFileTypes: true });
+      await import_fs_extra27.default.ensureDir(dataDir);
+      const entries = await import_fs_extra27.default.readdir(dataDir, { withFileTypes: true });
       const files = entries.filter((e) => e.isFile() && ALLOWED_EXTENSIONS.some((ext) => e.name.endsWith(ext))).map((e) => ({
         name: e.name,
         type: e.name.endsWith(".csv") ? "csv" : "json",
@@ -15215,12 +15758,12 @@ async function dataFileRoutes(fastify) {
   });
   fastify.get("/data-files/:filename", async (req, reply) => {
     try {
-      const filename = import_path33.default.basename(req.params.filename);
-      const filePath = import_path33.default.join(dataDir, filename);
-      if (!await import_fs_extra25.default.pathExists(filePath)) {
+      const filename = import_path35.default.basename(req.params.filename);
+      const filePath = import_path35.default.join(dataDir, filename);
+      if (!await import_fs_extra27.default.pathExists(filePath)) {
         return reply.status(404).send({ error: `Data file "${filename}" not found` });
       }
-      const raw = await import_fs_extra25.default.readFile(filePath, "utf8");
+      const raw = await import_fs_extra27.default.readFile(filePath, "utf8");
       let rows;
       if (filename.endsWith(".csv")) {
         rows = parseCSV(raw);
@@ -15241,14 +15784,14 @@ async function dataFileRoutes(fastify) {
       if (!filename) {
         return reply.status(400).send({ error: "filename is required" });
       }
-      const ext = import_path33.default.extname(filename).toLowerCase();
+      const ext = import_path35.default.extname(filename).toLowerCase();
       if (!ALLOWED_EXTENSIONS.includes(ext)) {
         return reply.status(400).send({ error: `Only ${ALLOWED_EXTENSIONS.join(", ")} files are allowed` });
       }
-      const safeName = import_path33.default.basename(filename);
-      const filePath = import_path33.default.join(dataDir, safeName);
-      await import_fs_extra25.default.ensureDir(dataDir);
-      await import_fs_extra25.default.writeFile(filePath, content, "utf8");
+      const safeName = import_path35.default.basename(filename);
+      const filePath = import_path35.default.join(dataDir, safeName);
+      await import_fs_extra27.default.ensureDir(dataDir);
+      await import_fs_extra27.default.writeFile(filePath, content, "utf8");
       let rowCount = 0;
       try {
         if (ext === ".csv") {
@@ -15271,12 +15814,12 @@ async function dataFileRoutes(fastify) {
   });
   fastify.put("/data-files/:filename", async (req, reply) => {
     try {
-      const filename = import_path33.default.basename(req.params.filename);
-      const filePath = import_path33.default.join(dataDir, filename);
+      const filename = import_path35.default.basename(req.params.filename);
+      const filePath = import_path35.default.join(dataDir, filename);
       const body = req.body;
       const content = String(body.content ?? "");
-      await import_fs_extra25.default.ensureDir(dataDir);
-      await import_fs_extra25.default.writeFile(filePath, content, "utf8");
+      await import_fs_extra27.default.ensureDir(dataDir);
+      await import_fs_extra27.default.writeFile(filePath, content, "utf8");
       logger43.info({ filename }, "Data file updated");
       return reply.send({ filename, path: `data/${filename}` });
     } catch (err) {
@@ -15285,12 +15828,12 @@ async function dataFileRoutes(fastify) {
   });
   fastify.delete("/data-files/:filename", async (req, reply) => {
     try {
-      const filename = import_path33.default.basename(req.params.filename);
-      const filePath = import_path33.default.join(dataDir, filename);
-      if (!await import_fs_extra25.default.pathExists(filePath)) {
+      const filename = import_path35.default.basename(req.params.filename);
+      const filePath = import_path35.default.join(dataDir, filename);
+      if (!await import_fs_extra27.default.pathExists(filePath)) {
         return reply.status(404).send({ error: `Data file "${filename}" not found` });
       }
-      await import_fs_extra25.default.remove(filePath);
+      await import_fs_extra27.default.remove(filePath);
       logger43.info({ filename }, "Data file deleted");
       return reply.status(204).send();
     } catch (err) {
@@ -15298,13 +15841,13 @@ async function dataFileRoutes(fastify) {
     }
   });
 }
-var import_path33, import_fs_extra25, logger43, ALLOWED_EXTENSIONS;
+var import_path35, import_fs_extra27, logger43, ALLOWED_EXTENSIONS;
 var init_data_files = __esm({
   "src/server/routes/data-files.ts"() {
     "use strict";
     init_cjs_shims();
-    import_path33 = __toESM(require("path"));
-    import_fs_extra25 = __toESM(require("fs-extra"));
+    import_path35 = __toESM(require("path"));
+    import_fs_extra27 = __toESM(require("fs-extra"));
     init_utils2();
     init_logger();
     logger43 = createChildLogger("routes/data-files");
@@ -15326,7 +15869,7 @@ function matchWeight(matchedOn) {
   }
 }
 async function searchRoutes(fastify) {
-  const testsDir = import_path34.default.join(fastify.rootDir, "tests");
+  const testsDir = import_path36.default.join(fastify.rootDir, "tests");
   fastify.get("/search", async (req, reply) => {
     const q = (req.query.q ?? "").trim();
     if (q.length < 2) {
@@ -15388,12 +15931,12 @@ async function searchRoutes(fastify) {
     }
   });
 }
-var import_path34;
+var import_path36;
 var init_search = __esm({
   "src/server/routes/search.ts"() {
     "use strict";
     init_cjs_shims();
-    import_path34 = __toESM(require("path"));
+    import_path36 = __toESM(require("path"));
     init_suite_store();
     init_case_store();
     init_utils2();
@@ -15674,13 +16217,13 @@ var init_flakiness = __esm({
 
 // src/storage/step-library-store.ts
 function libraryPath(rootDir) {
-  return import_path35.default.join(rootDir, "tests", ".step-library.json");
+  return import_path37.default.join(rootDir, "tests", ".step-library.json");
 }
 async function readLibrary(rootDir) {
   const filePath = libraryPath(rootDir);
-  if (!await import_fs_extra26.default.pathExists(filePath)) return [];
+  if (!await import_fs_extra28.default.pathExists(filePath)) return [];
   try {
-    const raw = await import_fs_extra26.default.readJson(filePath);
+    const raw = await import_fs_extra28.default.readJson(filePath);
     if (!Array.isArray(raw)) return [];
     return raw.map((item) => LibraryStepSchema.parse(item));
   } catch {
@@ -15689,7 +16232,7 @@ async function readLibrary(rootDir) {
 }
 async function writeLibrary(rootDir, steps) {
   const filePath = libraryPath(rootDir);
-  await import_fs_extra26.default.ensureDir(import_path35.default.dirname(filePath));
+  await import_fs_extra28.default.ensureDir(import_path37.default.dirname(filePath));
   await atomicWriteJson(filePath, steps);
 }
 async function addStep(rootDir, data) {
@@ -15721,13 +16264,13 @@ async function deleteStep(rootDir, id) {
   const filtered = steps.filter((s) => s.id !== id);
   await writeLibrary(rootDir, filtered);
 }
-var import_path35, import_fs_extra26, import_uuid3, import_zod20, LibraryStepSchema;
+var import_path37, import_fs_extra28, import_uuid3, import_zod20, LibraryStepSchema;
 var init_step_library_store = __esm({
   "src/storage/step-library-store.ts"() {
     "use strict";
     init_cjs_shims();
-    import_path35 = __toESM(require("path"));
-    import_fs_extra26 = __toESM(require("fs-extra"));
+    import_path37 = __toESM(require("path"));
+    import_fs_extra28 = __toESM(require("fs-extra"));
     import_uuid3 = require("uuid");
     import_zod20 = require("zod");
     init_utils();
@@ -15867,26 +16410,44 @@ function buildCaptureScript() {
   }, 200);
 
   // \u2500\u2500 Detect iframe context \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
-  // When running inside an iframe, compute a selector for the iframe element
-  // as seen from the parent frame. This lets Node.js use page.frameLocator().
   var _frameSelector = '';
   try {
     if (window !== window.top && window.frameElement) {
       var iframe = window.frameElement;
-      if (iframe.id) { _frameSelector = '#' + iframe.id; }
-      else if (iframe.getAttribute('name')) { _frameSelector = 'iframe[name="' + iframe.getAttribute('name') + '"]'; }
-      else if (iframe.getAttribute('data-testid')) { _frameSelector = 'iframe[data-testid="' + iframe.getAttribute('data-testid') + '"]'; }
-      else if (iframe.getAttribute('src')) {
-        // Use src but strip query params for stability
+      if (iframe.id) {
+        _frameSelector = '#' + CSS.escape(iframe.id);
+      } else if (iframe.getAttribute('name')) {
+        _frameSelector = 'iframe[name="' + iframe.getAttribute('name') + '"]';
+      } else if (iframe.getAttribute('data-testid')) {
+        _frameSelector = 'iframe[data-testid="' + iframe.getAttribute('data-testid') + '"]';
+      } else if (iframe.getAttribute('src')) {
         var src = iframe.getAttribute('src').split('?')[0];
         _frameSelector = 'iframe[src*="' + src + '"]';
+      } else {
+        // Positional fallback \u2014 find this iframe's index among all iframes
+        var allIframes = document.querySelectorAll ? [] : [];
+        try {
+          var parent = iframe.ownerDocument;
+          if (parent) {
+            var iframeList = parent.querySelectorAll('iframe');
+            var idx = Array.from(iframeList).indexOf(iframe);
+            _frameSelector = idx >= 0 ? 'iframe:nth-of-type(' + (idx + 1) + ')' : 'iframe';
+          }
+        } catch(pe) { _frameSelector = 'iframe'; }
       }
-      else { _frameSelector = 'iframe'; }
     }
-  } catch(e) {
-    // Cross-origin iframe \u2014 frameElement is null, try parent postMessage approach
-    // For same-origin iframes this works; cross-origin will use fallback
-    _frameSelector = '';
+  } catch(e) { _frameSelector = ''; }
+
+  // \u2500\u2500 Shadow DOM detection \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+  // Returns "host-selector >> inner-selector" when element is inside a shadow root.
+  function getShadowPath(el) {
+    var root = el.getRootNode();
+    if (!root || !(root instanceof ShadowRoot)) return null;
+    var host = root.host;
+    if (!host) return null;
+    var hostSel = cssPath(host);
+    var innerSel = cssPathLocal(el, root);
+    return hostSel + ' >> ' + innerSel;
   }
 
   // \u2500\u2500 Collect element metadata \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
@@ -15910,23 +16471,28 @@ function buildCaptureScript() {
       cssPath: cssPath(el),
       classes: Array.from(el.classList || []).join(' '),
     };
-    if (_frameSelector) { meta.frameSelector = _frameSelector; }
+    if (_frameSelector) meta.frameSelector = _frameSelector;
+    // Shadow DOM: record the pierce path
+    var sp = getShadowPath(el);
+    if (sp) meta.shadowPath = sp;
     return meta;
   }
 
   function getLabel(el) {
-    if (!el.id) {
-      var wrap = el.closest('label');
-      if (wrap) {
-        var clone = wrap.cloneNode(true);
-        clone.querySelectorAll('input,select,textarea').forEach(function(i) { i.remove(); });
-        var t = clone.textContent.trim();
-        if (t) return t;
-      }
-      return null;
+    // Try in current root (works inside shadow roots too)
+    var root = el.getRootNode() || document;
+    if (el.id) {
+      var lbl = root.querySelector('label[for="' + CSS.escape(el.id) + '"]');
+      if (lbl) return lbl.textContent.trim();
+    }
+    var wrap = el.closest('label');
+    if (wrap) {
+      var clone = wrap.cloneNode(true);
+      clone.querySelectorAll('input,select,textarea').forEach(function(i) { i.remove(); });
+      var t = clone.textContent.trim();
+      if (t) return t;
     }
-    var lbl = document.querySelector('label[for="' + CSS.escape(el.id) + '"]');
-    return lbl ? lbl.textContent.trim() : null;
+    return null;
   }
 
   function visText(el) {
@@ -15934,13 +16500,33 @@ function buildCaptureScript() {
     return t.trim().replace(/\\s+/g, ' ').slice(0, 80);
   }
 
+  // CSS path that stops at the nearest shadow root boundary (for shadow-dom inner selector)
+  function cssPathLocal(el, root) {
+    if (el.id) return '#' + CSS.escape(el.id);
+    var parts = [], cur = el;
+    for (var i = 0; i < 4 && cur && cur !== root && cur !== document.body; i++) {
+      var sel = cur.tagName.toLowerCase();
+      if (cur.id) { parts.unshift('#' + CSS.escape(cur.id)); break; }
+      var cls = Array.from(cur.classList || []).filter(function(c) { return !/^(ng-|_|css-|sc-|jsx-|emotion)/.test(c); }).slice(0, 2);
+      if (cls.length) sel += '.' + cls.map(function(c) { return CSS.escape(c); }).join('.');
+      var p = cur.parentElement || (cur.parentNode !== root ? cur.parentNode : null);
+      if (p && p.children) {
+        var sibs = Array.from(p.children).filter(function(s) { return s.tagName === cur.tagName; });
+        if (sibs.length > 1) sel += ':nth-child(' + (sibs.indexOf(cur) + 1) + ')';
+      }
+      parts.unshift(sel);
+      cur = cur.parentElement;
+    }
+    return parts.join(' > ') || el.tagName.toLowerCase();
+  }
+
   function cssPath(el) {
     if (el.id) return '#' + CSS.escape(el.id);
     var parts = [], cur = el;
     for (var i = 0; i < 4 && cur && cur !== document.body; i++) {
       var sel = cur.tagName.toLowerCase();
       if (cur.id) { parts.unshift('#' + CSS.escape(cur.id)); break; }
-      var cls = Array.from(cur.classList).filter(function(c) { return !/^(ng-|_|css-|sc-|jsx-|emotion)/.test(c); }).slice(0, 2);
+      var cls = Array.from(cur.classList || []).filter(function(c) { return !/^(ng-|_|css-|sc-|jsx-|emotion)/.test(c); }).slice(0, 2);
       if (cls.length) sel += '.' + cls.map(function(c) { return CSS.escape(c); }).join('.');
       var p = cur.parentElement;
       if (p) {
@@ -15953,7 +16539,7 @@ function buildCaptureScript() {
     return parts.join(' > ');
   }
 
-  // Human-readable element description for instructions
+  // Human-readable element description
   function descEl(meta) {
     var t = meta.tag, ty = meta.type;
     var nm = meta.ariaLabel || meta.labelText || meta.innerText || meta.placeholder || meta.title || meta.testId;
@@ -15972,12 +16558,11 @@ function buildCaptureScript() {
     return 'the "' + (nm || t) + '" element';
   }
 
-  // Track the currently active input \u2014 only record its value when the user LEAVES the field
-  var activeInput = null;   // the DOM element being typed into
-  var pendingInput = null;  // the action payload to send
+  // Track the currently active input \u2014 only record value when user LEAVES the field
+  var activeInput = null;
+  var pendingInput = null;
   function flushInput() {
     if (pendingInput && activeInput) {
-      // Grab the FINAL value at flush time, not the value when input event fired
       var meta = getMeta(activeInput);
       var desc = descEl(meta);
       pendingInput.instruction = 'Enter "' + activeInput.value + '" in ' + desc;
@@ -15989,7 +16574,7 @@ function buildCaptureScript() {
     activeInput = null;
   }
 
-  // Banner + styles (only in main frame \u2014 iframes don't need the banner)
+  // Banner (main frame only)
   function ensureBanner() {
     if (window !== window.top) return;
     if (document.getElementById('__am-banner')) return;
@@ -15999,7 +16584,7 @@ function buildCaptureScript() {
     var b = document.createElement('div');
     b.id = '__am-banner';
     b.style.cssText = 'position:fixed;top:0;left:0;right:0;z-index:2147483647;background:linear-gradient(90deg,#1e1e2e,#2d1b3d);color:#fff;font:13px system-ui,sans-serif;padding:6px 16px;display:flex;align-items:center;box-shadow:0 2px 8px rgba(0,0,0,0.3);gap:12px;';
-    b.innerHTML = '<span style="display:inline-flex;align-items:center;gap:6px"><span style="width:8px;height:8px;border-radius:50%;background:#ef4444;animation:__amp 1.5s infinite"></span><b>Recording</b></span><span style="opacity:.65;font-size:12px">Shift+Click = assert &nbsp;|&nbsp; Ctrl+Shift+Click = soft assert &nbsp;|&nbsp; Ctrl+Shift+U = URL &nbsp;|&nbsp; Ctrl+Shift+T = title</span>';
+    b.innerHTML = '<span style="display:inline-flex;align-items:center;gap:6px"><span style="width:8px;height:8px;border-radius:50%;background:#ef4444;animation:__amp 1.5s infinite"></span><b>Recording</b></span><span style="opacity:.65;font-size:12px">Shift+Click = assert &nbsp;|&nbsp; Ctrl+Shift+U = URL &nbsp;|&nbsp; Ctrl+Shift+T = title</span>';
     document.body.appendChild(b);
   }
   if (document.body) ensureBanner();
@@ -16008,27 +16593,31 @@ function buildCaptureScript() {
   // Hover highlight
   var lastH = null;
   document.addEventListener('mouseover', function(e) {
-    var el = e.target;
+    var el = (e.composedPath && e.composedPath()[0]) || e.target;
     if (!el || !el.tagName || !el.classList) return;
-    if (el.id === '__am-banner' || el.closest('#__am-banner')) return;
+    if (el.id === '__am-banner' || el.closest && el.closest('#__am-banner')) return;
     if (lastH && lastH !== el && lastH.classList) lastH.classList.remove('__am-hh');
     el.classList.add('__am-hh');
     lastH = el;
   }, true);
   document.addEventListener('mouseout', function(e) {
-    if (e.target && e.target.classList) e.target.classList.remove('__am-hh');
+    var el = (e.composedPath && e.composedPath()[0]) || e.target;
+    if (el && el.classList) el.classList.remove('__am-hh');
   }, true);
 
   // \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
-  //  EVENT LISTENERS \u2014 send raw metadata, Node.js resolves locators
+  //  EVENT LISTENERS
+  //  composedPath()[0] gives the real target inside shadow roots.
+  //  Regular e.target is re-targeted to the shadow host at the boundary.
   // \u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550\u2550
 
-  // Click (normal = action, Shift = assert)
+  // Click
   document.addEventListener('click', function(e) {
     flushInput();
-    var el = e.target;
+    // Use composedPath to pierce shadow DOM \u2014 get the real target element
+    var el = (e.composedPath && e.composedPath()[0]) || e.target;
     if (!el || !el.tagName) return;
-    if (el.id === '__am-banner' || el.closest('#__am-banner')) return;
+    if (el.id === '__am-banner' || (el.closest && el.closest('#__am-banner'))) return;
 
     var meta = getMeta(el);
     var desc = descEl(meta);
@@ -16039,7 +16628,6 @@ function buildCaptureScript() {
       var isSoft = e.ctrlKey || e.metaKey;
       var prefix = isSoft ? 'Soft verify ' : 'Verify ';
       if (el.classList) { el.classList.add('__am-ah'); setTimeout(function() { el.classList.remove('__am-ah'); }, 1200); }
-
       var inst = '';
       if (meta.tag === 'input' || meta.tag === 'textarea') {
         inst = meta.value ? prefix + desc + ' has value "' + meta.value + '"' : prefix + desc + ' is visible';
@@ -16052,7 +16640,7 @@ function buildCaptureScript() {
       return;
     }
 
-    // Normal click
+    // Normal click \u2014 skip plain text inputs (handled by fill)
     if (meta.tag === 'input' && ['submit','button','checkbox','radio','file'].indexOf(meta.type) < 0) return;
     if (meta.tag === 'textarea' || meta.tag === 'option') return;
 
@@ -16062,28 +16650,28 @@ function buildCaptureScript() {
     safeSend(JSON.stringify({ action: action, instruction: instruction, meta: meta, url: location.href }));
   }, true);
 
-  // Input \u2014 just mark this element as actively being typed into (NO timer, NO intermediate captures)
+  // Input \u2014 mark element as active; capture final value on blur/Enter
   document.addEventListener('input', function(e) {
-    var el = e.target; if (!el || !el.tagName) return;
-    if (el.tagName.toLowerCase() !== 'input' && el.tagName.toLowerCase() !== 'textarea') return;
+    var el = (e.composedPath && e.composedPath()[0]) || e.target;
+    if (!el || !el.tagName) return;
+    var t = el.tagName.toLowerCase();
+    if (t !== 'input' && t !== 'textarea') return;
     var ty = (el.getAttribute('type') || '').toLowerCase();
     if (['checkbox','radio','submit','button','file'].indexOf(ty) >= 0) return;
-    // Just mark as active \u2014 we'll capture the FINAL value on blur/click/Enter
     activeInput = el;
     pendingInput = { action: 'fill', instruction: '', meta: null, value: '', url: location.href };
   }, true);
 
-  // Blur \u2014 user left the field \u2192 capture the FINAL value
+  // Blur \u2014 user left the field \u2192 capture final value
   document.addEventListener('blur', function(e) {
-    var el = e.target;
-    if (el && el === activeInput && pendingInput) {
-      flushInput();
-    }
+    var el = (e.composedPath && e.composedPath()[0]) || e.target;
+    if (el && el === activeInput && pendingInput) flushInput();
   }, true);
 
   // Select change
   document.addEventListener('change', function(e) {
-    var el = e.target; if (!el || el.tagName.toLowerCase() !== 'select') return;
+    var el = (e.composedPath && e.composedPath()[0]) || e.target;
+    if (!el || el.tagName.toLowerCase() !== 'select') return;
     flushInput();
     var meta = getMeta(el), desc = descEl(meta);
     var selText = el.options[el.selectedIndex] ? el.options[el.selectedIndex].text : el.value;
@@ -16092,6 +16680,7 @@ function buildCaptureScript() {
 
   // Keyboard
   document.addEventListener('keydown', function(e) {
+    // \u2500\u2500 Assertion shortcuts \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
     if (e.ctrlKey && e.shiftKey && e.key.toLowerCase() === 'u') {
       e.preventDefault(); e.stopPropagation(); flushInput();
       var b = document.getElementById('__am-banner');
@@ -16107,21 +16696,67 @@ function buildCaptureScript() {
       safeSend(JSON.stringify({ action: 'assert', instruction: 'Verify the page title is "' + document.title + '"', meta: null, value: document.title, url: location.href }));
       return;
     }
+
+    var el = (e.composedPath && e.composedPath()[0]) || e.target;
+    var tag = el && el.tagName ? el.tagName.toLowerCase() : '';
+    var isInput = tag === 'input' || tag === 'textarea';
+
+    // \u2500\u2500 Enter \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
     if (e.key === 'Enter') {
       flushInput();
-      var el = e.target;
-      if (el && el.tagName) {
-        var t = el.tagName.toLowerCase();
-        if (t === 'input' || t === 'textarea') {
-          var meta = getMeta(el), desc = descEl(meta);
-          safeSend(JSON.stringify({ action: 'press', instruction: 'Press Enter on ' + desc, meta: meta, value: 'Enter', url: location.href }));
-        }
+      if (isInput) {
+        var meta = getMeta(el), desc = descEl(meta);
+        safeSend(JSON.stringify({ action: 'press', instruction: 'Press Enter on ' + desc, meta: meta, value: 'Enter', url: location.href }));
       }
-    } else if (e.key === 'Escape') {
+      return;
+    }
+
+    // \u2500\u2500 Escape \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    if (e.key === 'Escape') {
       flushInput();
       safeSend(JSON.stringify({ action: 'press', instruction: 'Press Escape', meta: null, value: 'Escape', url: location.href }));
-    } else if (e.key === 'Tab') {
+      return;
+    }
+
+    // \u2500\u2500 Tab \u2014 flush active input, then record the Tab key press \u2500\u2500\u2500\u2500\u2500\u2500
+    if (e.key === 'Tab') {
       flushInput();
+      var tabKey = e.shiftKey ? 'Shift+Tab' : 'Tab';
+      if (isInput) {
+        var meta2 = getMeta(el), desc2 = descEl(meta2);
+        safeSend(JSON.stringify({ action: 'press', instruction: 'Press ' + tabKey + ' on ' + desc2, meta: meta2, value: tabKey, url: location.href }));
+      }
+      return;
+    }
+
+    // \u2500\u2500 Keyboard shortcuts (Ctrl/Meta + key) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    if ((e.ctrlKey || e.metaKey) && !e.shiftKey) {
+      var shortcutMap = { a: 'Control+A', c: 'Control+C', v: 'Control+V', x: 'Control+X', z: 'Control+Z', y: 'Control+Y' };
+      var k = e.key.toLowerCase();
+      if (shortcutMap[k]) {
+        // Only record Ctrl+A (select all) explicitly \u2014 copy/paste/undo are usually not test steps
+        if (k === 'a') {
+          flushInput();
+          safeSend(JSON.stringify({ action: 'press', instruction: 'Press Ctrl+A to select all', meta: isInput ? getMeta(el) : null, value: 'Control+A', url: location.href }));
+        }
+        return; // don't treat as a character key
+      }
+    }
+
+    // \u2500\u2500 Arrow keys (only when NOT inside an input \u2014 avoids noise) \u2500\u2500\u2500
+    if (['ArrowDown','ArrowUp','ArrowLeft','ArrowRight'].indexOf(e.key) >= 0 && !isInput) {
+      safeSend(JSON.stringify({ action: 'press', instruction: 'Press ' + e.key, meta: null, value: e.key, url: location.href }));
+      return;
+    }
+
+    // \u2500\u2500 Space on buttons / interactive non-inputs \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
+    if (e.key === ' ' && !isInput && el && ['button','a','[role=button]'].some(function(s) {
+      return tag === s.replace('[role=button]','') || (el.getAttribute && el.getAttribute('role') === 'button');
+    })) {
+      flushInput();
+      var meta3 = getMeta(el), desc3 = descEl(meta3);
+      safeSend(JSON.stringify({ action: 'press', instruction: 'Press Space on ' + desc3, meta: meta3, value: ' ', url: location.href }));
+      return;
     }
   }, true);
 })();
@@ -16129,6 +16764,10 @@ function buildCaptureScript() {
 }
 async function resolveLocator(page, meta) {
   const candidates = [];
+  if (meta.shadowPath) {
+    const framePrefix2 = meta.frameSelector ? `frameLocator('${esc(meta.frameSelector)}').` : "";
+    return `${framePrefix2}locator('${esc(meta.shadowPath)}')`;
+  }
   const inIframe = !!meta.frameSelector;
   const framePrefix = inIframe ? `frameLocator('${esc(meta.frameSelector)}').` : "";
   const base = inIframe ? page.frameLocator(meta.frameSelector) : page;
@@ -16353,6 +16992,21 @@ var init_recorder = __esm({
           this._setLastUserActionTime = (t) => {
             lastUserActionTime = t;
           };
+          this.page.on("dialog", async (dialog) => {
+            if (!this.running) return;
+            const dialogType = dialog.type();
+            const message = dialog.message();
+            await dialog.accept().catch(() => {
+            });
+            for (let i = this.actions.length - 1; i >= 0; i--) {
+              const a = this.actions[i];
+              if (["click", "fill", "check", "uncheck", "select", "press"].includes(a.action)) {
+                a.dialogHandler = { type: "accept", dialogType, message };
+                break;
+              }
+            }
+            logger44.debug({ dialogType, message }, "Dialog auto-accepted and tagged on triggering action");
+          });
           this.page.on("close", () => {
             if (this.running) {
               logger44.info("Browser closed by user \u2014 stopping recorder");
@@ -16410,7 +17064,8 @@ var init_recorder = __esm({
             url: parsed.url,
             timestamp: Date.now(),
             ...parsed.soft ? { soft: true } : {},
-            ...meta?.frameSelector ? { frameSelector: meta.frameSelector } : {}
+            ...meta?.frameSelector ? { frameSelector: meta.frameSelector } : {},
+            ...meta?.shadowPath ? { shadowPath: meta.shadowPath } : {}
           };
           this.actions.push(action);
           this.options.onAction(action);
@@ -16519,6 +17174,564 @@ var init_recorder2 = __esm({
   }
 });
 
+// src/server/routes/faker.ts
+var fakerRoutes;
+var init_faker2 = __esm({
+  "src/server/routes/faker.ts"() {
+    "use strict";
+    init_cjs_shims();
+    init_data_generator();
+    fakerRoutes = async (app) => {
+      app.get("/faker/generators", async (_req, reply) => {
+        const generators = getAvailableGenerators();
+        return reply.send(generators);
+      });
+    };
+  }
+});
+
+// src/server/routes/visual-regression.ts
+async function visualRegressionRoutes(fastify) {
+  const rootDir = fastify.rootDir;
+  fastify.get("/visual-regression/config", async (_req, reply) => {
+    try {
+      const config = await readVisualConfig(rootDir);
+      return reply.send(config);
+    } catch (err) {
+      return sendError(reply, 500, "Failed to read visual-regression config", err);
+    }
+  });
+  fastify.put("/visual-regression/config", async (req, reply) => {
+    try {
+      const body = req.body;
+      const current = await readVisualConfig(rootDir);
+      const updated = {
+        enabled: typeof body.enabled === "boolean" ? body.enabled : current.enabled,
+        defaultThreshold: typeof body.defaultThreshold === "number" ? body.defaultThreshold : current.defaultThreshold,
+        fullPage: typeof body.fullPage === "boolean" ? body.fullPage : current.fullPage,
+        maskSelectors: Array.isArray(body.maskSelectors) ? body.maskSelectors : current.maskSelectors
+      };
+      await writeVisualConfig(rootDir, updated);
+      return reply.send(updated);
+    } catch (err) {
+      return sendError(reply, 500, "Failed to save visual-regression config", err);
+    }
+  });
+  fastify.get("/visual-regression/baselines", async (_req, reply) => {
+    try {
+      const baselines = await listBaselines(rootDir);
+      return reply.send(baselines);
+    } catch (err) {
+      return sendError(reply, 500, "Failed to list baselines", err);
+    }
+  });
+  fastify.delete("/visual-regression/baselines", async (req, reply) => {
+    try {
+      const { path: baselinePath2 } = req.body;
+      if (!baselinePath2) {
+        return reply.status(400).send({ error: 'Missing "path" in request body' });
+      }
+      await deleteBaseline(rootDir, baselinePath2);
+      return reply.send({ ok: true });
+    } catch (err) {
+      return sendError(reply, 500, "Failed to delete baseline", err);
+    }
+  });
+  fastify.post("/visual-regression/baselines/update", async (req, reply) => {
+    try {
+      const { actualPath, baselinePath: baselinePath2 } = req.body;
+      if (!actualPath || !baselinePath2) {
+        return reply.status(400).send({ error: "Missing actualPath or baselinePath" });
+      }
+      if (!await import_fs_extra29.default.pathExists(actualPath)) {
+        return reply.status(404).send({ error: "Actual screenshot not found" });
+      }
+      await import_fs_extra29.default.ensureDir(import_path38.default.dirname(baselinePath2));
+      await import_fs_extra29.default.copy(actualPath, baselinePath2, { overwrite: true });
+      return reply.send({ ok: true });
+    } catch (err) {
+      return sendError(reply, 500, "Failed to update baseline", err);
+    }
+  });
+  fastify.get("/visual-regression/diffs", async (_req, reply) => {
+    try {
+      const runs = await listDiffRuns(rootDir);
+      return reply.send(runs);
+    } catch (err) {
+      return sendError(reply, 500, "Failed to list diff runs", err);
+    }
+  });
+  fastify.get("/visual-regression/diffs/:runId", async (req, reply) => {
+    try {
+      const { runId } = req.params;
+      const summary = await readDiffSummary(rootDir, runId);
+      return reply.send(summary);
+    } catch (err) {
+      return sendError(reply, 500, "Failed to read diff summary", err);
+    }
+  });
+  fastify.patch("/visual-regression/diffs/:runId/:stepId", async (req, reply) => {
+    try {
+      const { runId, stepId } = req.params;
+      const { status } = req.body;
+      if (!["approved", "rejected"].includes(status)) {
+        return reply.status(400).send({ error: 'Status must be "approved" or "rejected"' });
+      }
+      const updated = await updateDiffStatus(rootDir, runId, stepId, status);
+      return reply.send(updated);
+    } catch (err) {
+      return sendError(reply, 500, "Failed to update diff status", err);
+    }
+  });
+  fastify.post("/visual-regression/diffs/:runId/approve-all", async (req, reply) => {
+    try {
+      const { runId } = req.params;
+      const updated = await approveAllDiffs(rootDir, runId);
+      return reply.send(updated);
+    } catch (err) {
+      return sendError(reply, 500, "Failed to approve all diffs", err);
+    }
+  });
+  fastify.get("/visual-regression/image/*", async (req, reply) => {
+    try {
+      const rawPath = req.params["*"];
+      if (!rawPath) {
+        return reply.status(400).send({ error: "Missing image path" });
+      }
+      const imagePath = import_path38.default.resolve(rootDir, rawPath);
+      if (!imagePath.startsWith(import_path38.default.resolve(rootDir))) {
+        return reply.status(403).send({ error: "Forbidden" });
+      }
+      if (!await import_fs_extra29.default.pathExists(imagePath)) {
+        return reply.status(404).send({ error: "Image not found" });
+      }
+      const ext = import_path38.default.extname(imagePath).toLowerCase();
+      const mimeMap = {
+        ".png": "image/png",
+        ".jpg": "image/jpeg",
+        ".jpeg": "image/jpeg",
+        ".webp": "image/webp"
+      };
+      const contentType = mimeMap[ext] ?? "application/octet-stream";
+      const buffer = await import_fs_extra29.default.readFile(imagePath);
+      return reply.type(contentType).send(buffer);
+    } catch (err) {
+      return sendError(reply, 500, "Failed to serve image", err);
+    }
+  });
+}
+var import_fs_extra29, import_path38;
+var init_visual_regression = __esm({
+  "src/server/routes/visual-regression.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_fs_extra29 = __toESM(require("fs-extra"));
+    import_path38 = __toESM(require("path"));
+    init_utils2();
+    init_visual_regression_store();
+  }
+});
+
+// src/storage/ci-store.ts
+function configPath2(rootDir) {
+  return import_path39.default.join(rootDir, ".assuremind", "ci-integration.json");
+}
+function qualityGatesDir(rootDir) {
+  return import_path39.default.join(rootDir, "results", "quality-gates");
+}
+function qualityGateResultPath(rootDir, runId) {
+  return import_path39.default.join(qualityGatesDir(rootDir), `${runId}.json`);
+}
+async function readCiConfig(rootDir) {
+  const filePath = configPath2(rootDir);
+  if (!await import_fs_extra30.default.pathExists(filePath)) {
+    return CiIntegrationConfigSchema.parse({});
+  }
+  try {
+    const raw = await import_fs_extra30.default.readJson(filePath);
+    return CiIntegrationConfigSchema.parse(raw);
+  } catch {
+    return CiIntegrationConfigSchema.parse({});
+  }
+}
+async function writeCiConfig(rootDir, config) {
+  const filePath = configPath2(rootDir);
+  const validated = CiIntegrationConfigSchema.parse(config);
+  await import_fs_extra30.default.ensureDir(import_path39.default.dirname(filePath));
+  await atomicWriteJson(filePath, validated);
+}
+async function listQualityGateResults(rootDir) {
+  const dir = qualityGatesDir(rootDir);
+  if (!await import_fs_extra30.default.pathExists(dir)) return [];
+  try {
+    const files = await import_fs_extra30.default.readdir(dir);
+    const jsonFiles = files.filter((f) => f.endsWith(".json")).sort().reverse();
+    const results = [];
+    for (const file of jsonFiles) {
+      try {
+        const raw = await import_fs_extra30.default.readJson(import_path39.default.join(dir, file));
+        results.push(QualityGateResultSchema.parse(raw));
+      } catch {
+      }
+    }
+    return results;
+  } catch {
+    return [];
+  }
+}
+async function readQualityGateResult(rootDir, runId) {
+  const filePath = qualityGateResultPath(rootDir, runId);
+  if (!await import_fs_extra30.default.pathExists(filePath)) return null;
+  try {
+    const raw = await import_fs_extra30.default.readJson(filePath);
+    return QualityGateResultSchema.parse(raw);
+  } catch {
+    return null;
+  }
+}
+var import_path39, import_fs_extra30, import_zod23, NotificationTrigger, SlackConfigSchema, EmailConfigSchema, TeamsConfigSchema, CustomWebhookConfigSchema, CiIntegrationConfigSchema, GateResultSchema, QualityGateResultSchema;
+var init_ci_store = __esm({
+  "src/storage/ci-store.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_path39 = __toESM(require("path"));
+    import_fs_extra30 = __toESM(require("fs-extra"));
+    import_zod23 = require("zod");
+    init_utils();
+    NotificationTrigger = import_zod23.z.enum(["every-run", "failure", "healing"]);
+    SlackConfigSchema = import_zod23.z.object({
+      enabled: import_zod23.z.boolean().default(false),
+      webhookUrl: import_zod23.z.string().default(""),
+      on: import_zod23.z.array(NotificationTrigger).default(["failure"])
+    });
+    EmailConfigSchema = import_zod23.z.object({
+      enabled: import_zod23.z.boolean().default(false),
+      recipients: import_zod23.z.array(import_zod23.z.string()).default([]),
+      on: import_zod23.z.array(NotificationTrigger).default(["failure"])
+    });
+    TeamsConfigSchema = import_zod23.z.object({
+      enabled: import_zod23.z.boolean().default(false),
+      webhookUrl: import_zod23.z.string().default(""),
+      on: import_zod23.z.array(NotificationTrigger).default(["failure"])
+    });
+    CustomWebhookConfigSchema = import_zod23.z.object({
+      enabled: import_zod23.z.boolean().default(false),
+      url: import_zod23.z.string().default(""),
+      headers: import_zod23.z.record(import_zod23.z.string()).default({}),
+      on: import_zod23.z.array(NotificationTrigger).default(["failure"])
+    });
+    CiIntegrationConfigSchema = import_zod23.z.object({
+      prComments: import_zod23.z.object({
+        enabled: import_zod23.z.boolean().default(false),
+        provider: import_zod23.z.enum(["github", "gitlab", "azure-devops"]).default("github"),
+        includeHealingSummary: import_zod23.z.boolean().default(true),
+        includeVisualDiffs: import_zod23.z.boolean().default(false)
+      }).default({}),
+      qualityGate: import_zod23.z.object({
+        enabled: import_zod23.z.boolean().default(true),
+        minPassRate: import_zod23.z.number().min(0).max(100).default(95),
+        maxFlakyRate: import_zod23.z.number().min(0).max(100).default(10),
+        maxDuration: import_zod23.z.number().min(0).default(0),
+        requireTags: import_zod23.z.array(import_zod23.z.string()).default([])
+      }).default({}),
+      notifications: import_zod23.z.object({
+        slack: SlackConfigSchema.default({}),
+        email: EmailConfigSchema.default({}),
+        teams: TeamsConfigSchema.default({}),
+        customWebhook: CustomWebhookConfigSchema.default({})
+      }).default({})
+    });
+    GateResultSchema = import_zod23.z.object({
+      name: import_zod23.z.string(),
+      passed: import_zod23.z.boolean(),
+      expected: import_zod23.z.string(),
+      actual: import_zod23.z.string()
+    });
+    QualityGateResultSchema = import_zod23.z.object({
+      passed: import_zod23.z.boolean(),
+      runId: import_zod23.z.string(),
+      timestamp: import_zod23.z.string(),
+      metrics: import_zod23.z.object({
+        passRate: import_zod23.z.number(),
+        totalTests: import_zod23.z.number(),
+        passed: import_zod23.z.number(),
+        failed: import_zod23.z.number(),
+        skipped: import_zod23.z.number(),
+        duration: import_zod23.z.number(),
+        healingCount: import_zod23.z.number()
+      }),
+      gates: import_zod23.z.array(GateResultSchema),
+      reason: import_zod23.z.string().optional()
+    });
+  }
+});
+
+// src/engine/ci/notifier.ts
+function formatDuration(seconds) {
+  const m = Math.floor(seconds / 60);
+  const s = seconds % 60;
+  return m > 0 ? `${m}m ${s}s` : `${s}s`;
+}
+function buildSlackPayload(runResult) {
+  const total = runResult.passed + runResult.failed + runResult.skipped;
+  const passRate = total > 0 ? (runResult.passed / total * 100).toFixed(1) : "0";
+  const status = runResult.failed > 0 ? ":x: Failed" : ":white_check_mark: Passed";
+  const failedTests = [];
+  if (runResult.suiteResults) {
+    for (const suite of runResult.suiteResults) {
+      for (const c of suite.cases) {
+        if (c.status === "failed") {
+          failedTests.push(c.caseName);
+        }
+      }
+    }
+  }
+  const blocks = [
+    {
+      type: "header",
+      text: { type: "plain_text", text: "Assuremind Test Results", emoji: true }
+    },
+    {
+      type: "section",
+      fields: [
+        { type: "mrkdwn", text: `*Status:*
+${status}` },
+        { type: "mrkdwn", text: `*Pass Rate:*
+${passRate}% (${runResult.passed}/${total})` },
+        { type: "mrkdwn", text: `*Failed:*
+${runResult.failed}` },
+        { type: "mrkdwn", text: `*Duration:*
+${formatDuration(runResult.duration)}` }
+      ]
+    }
+  ];
+  if (failedTests.length > 0) {
+    blocks.push({
+      type: "section",
+      text: {
+        type: "mrkdwn",
+        text: `*Failed Tests:*
+${failedTests.map((t) => `\u2022 ${t}`).join("\n")}`
+      }
+    });
+  }
+  blocks.push({
+    type: "context",
+    elements: [{ type: "mrkdwn", text: ":robot_face: Generated by Assuremind" }]
+  });
+  return { blocks };
+}
+function buildTeamsPayload(runResult) {
+  const total = runResult.passed + runResult.failed + runResult.skipped;
+  const passRate = total > 0 ? (runResult.passed / total * 100).toFixed(1) : "0";
+  const statusColor = runResult.failed > 0 ? "attention" : "good";
+  const facts = [
+    { title: "Pass Rate", value: `${passRate}% (${runResult.passed}/${total})` },
+    { title: "Failed", value: `${runResult.failed}` },
+    { title: "Skipped", value: `${runResult.skipped}` },
+    { title: "Duration", value: formatDuration(runResult.duration) }
+  ];
+  return {
+    type: "message",
+    attachments: [
+      {
+        contentType: "application/vnd.microsoft.card.adaptive",
+        content: {
+          $schema: "http://adaptivecards.io/schemas/adaptive-card.json",
+          type: "AdaptiveCard",
+          version: "1.4",
+          body: [
+            {
+              type: "TextBlock",
+              text: "Assuremind Test Results",
+              weight: "bolder",
+              size: "medium",
+              color: statusColor
+            },
+            {
+              type: "FactSet",
+              facts
+            }
+          ]
+        }
+      }
+    ]
+  };
+}
+async function sendSlack(webhookUrl, runResult) {
+  const payload = buildSlackPayload(runResult);
+  logger46.info("Sending Slack notification");
+  const response = await fetch(webhookUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload)
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    logger46.error({ status: response.status, text }, "Failed to send Slack notification");
+  } else {
+    logger46.info("Slack notification sent");
+  }
+}
+async function sendTeams(webhookUrl, runResult) {
+  const payload = buildTeamsPayload(runResult);
+  logger46.info("Sending Teams notification");
+  const response = await fetch(webhookUrl, {
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(payload)
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    logger46.error({ status: response.status, text }, "Failed to send Teams notification");
+  } else {
+    logger46.info("Teams notification sent");
+  }
+}
+async function sendCustomWebhook(url, headers, runResult) {
+  logger46.info({ url }, "Sending custom webhook notification");
+  const response = await fetch(url, {
+    method: "POST",
+    headers: { "Content-Type": "application/json", ...headers },
+    body: JSON.stringify({
+      source: "assuremind",
+      runId: runResult.runId,
+      passed: runResult.passed,
+      failed: runResult.failed,
+      skipped: runResult.skipped,
+      duration: runResult.duration,
+      timestamp: (/* @__PURE__ */ new Date()).toISOString()
+    })
+  });
+  if (!response.ok) {
+    const text = await response.text();
+    logger46.error({ status: response.status, text }, "Failed to send custom webhook notification");
+  } else {
+    logger46.info("Custom webhook notification sent");
+  }
+}
+async function sendTestNotification(channel, config) {
+  const dummyRun = {
+    runId: "test-notification",
+    passed: 10,
+    failed: 1,
+    skipped: 2,
+    duration: 45,
+    suiteResults: [
+      {
+        suiteId: "demo",
+        suiteName: "Demo Suite",
+        cases: [
+          { caseId: "c1", caseName: "Test notification", status: "passed" },
+          { caseId: "c2", caseName: "Example failed test", status: "failed", error: "This is a test notification" }
+        ]
+      }
+    ]
+  };
+  try {
+    switch (channel) {
+      case "slack": {
+        const { webhookUrl } = config.notifications.slack;
+        if (!webhookUrl) return { ok: false, error: "Slack webhook URL not configured" };
+        await sendSlack(webhookUrl, dummyRun);
+        return { ok: true };
+      }
+      case "teams": {
+        const { webhookUrl } = config.notifications.teams;
+        if (!webhookUrl) return { ok: false, error: "Teams webhook URL not configured" };
+        await sendTeams(webhookUrl, dummyRun);
+        return { ok: true };
+      }
+      case "custom": {
+        const { url, headers } = config.notifications.customWebhook;
+        if (!url) return { ok: false, error: "Custom webhook URL not configured" };
+        await sendCustomWebhook(url, headers, dummyRun);
+        return { ok: true };
+      }
+      default:
+        return { ok: false, error: `Unsupported channel: ${channel}` };
+    }
+  } catch (err) {
+    return { ok: false, error: err instanceof Error ? err.message : String(err) };
+  }
+}
+var logger46;
+var init_notifier = __esm({
+  "src/engine/ci/notifier.ts"() {
+    "use strict";
+    init_cjs_shims();
+    init_logger();
+    logger46 = createChildLogger("notifier");
+  }
+});
+
+// src/server/routes/ci-integration.ts
+async function ciIntegrationRoutes(fastify) {
+  const rootDir = fastify.rootDir;
+  fastify.get("/ci-integration/config", async (_req, reply) => {
+    try {
+      const config = await readCiConfig(rootDir);
+      return reply.send(config);
+    } catch (err) {
+      return sendError(reply, 500, "Failed to read CI integration config", err);
+    }
+  });
+  fastify.put("/ci-integration/config", async (req, reply) => {
+    try {
+      const config = req.body;
+      await writeCiConfig(rootDir, config);
+      const saved = await readCiConfig(rootDir);
+      return reply.send(saved);
+    } catch (err) {
+      return sendError(reply, 500, "Failed to save CI integration config", err);
+    }
+  });
+  fastify.get("/ci-integration/quality-gates", async (_req, reply) => {
+    try {
+      const results = await listQualityGateResults(rootDir);
+      return reply.send(results);
+    } catch (err) {
+      return sendError(reply, 500, "Failed to list quality gate results", err);
+    }
+  });
+  fastify.get("/ci-integration/quality-gates/:runId", async (req, reply) => {
+    try {
+      const result = await readQualityGateResult(rootDir, req.params.runId);
+      if (!result) return reply.status(404).send({ error: "Quality gate result not found" });
+      return reply.send(result);
+    } catch (err) {
+      return sendError(reply, 500, "Failed to read quality gate result", err);
+    }
+  });
+  fastify.post("/ci-integration/test-notification", async (req, reply) => {
+    const parsed = TestNotificationBody.safeParse(req.body);
+    if (!parsed.success) {
+      return reply.status(400).send({ error: "Invalid request", details: parsed.error.issues });
+    }
+    try {
+      const config = await readCiConfig(rootDir);
+      const result = await sendTestNotification(parsed.data.channel, config);
+      return reply.send(result);
+    } catch (err) {
+      return sendError(reply, 500, "Failed to send test notification", err);
+    }
+  });
+}
+var import_zod24, TestNotificationBody;
+var init_ci_integration = __esm({
+  "src/server/routes/ci-integration.ts"() {
+    "use strict";
+    init_cjs_shims();
+    import_zod24 = require("zod");
+    init_ci_store();
+    init_notifier();
+    init_utils2();
+    TestNotificationBody = import_zod24.z.object({
+      channel: import_zod24.z.enum(["slack", "teams", "custom"])
+    });
+  }
+});
+
 // src/server/index.ts
 var server_exports = {};
 __export(server_exports, {
@@ -16561,17 +17774,20 @@ async function startServer(options) {
   await fastify.register(flakinessRoutes, { prefix: "/api" });
   await fastify.register(stepLibraryRoutes, { prefix: "/api" });
   await fastify.register(recorderRoutes, { prefix: "/api" });
+  await fastify.register(fakerRoutes, { prefix: "/api" });
+  await fastify.register(visualRegressionRoutes, { prefix: "/api" });
+  await fastify.register(ciIntegrationRoutes, { prefix: "/api" });
   await registerStatic(fastify, rootDir);
   await fastify.listen({ port, host: "127.0.0.1" });
-  logger46.info({ port, rootDir }, `Assuremind Studio listening on http://127.0.0.1:${port}`);
+  logger47.info({ port, rootDir }, `Assuremind Studio listening on http://127.0.0.1:${port}`);
   return {
     async close() {
       await fastify.close();
-      logger46.info("Server closed");
+      logger47.info("Server closed");
     }
   };
 }
-var import_fastify, import_cors, import_websocket, logger46;
+var import_fastify, import_cors, import_websocket, logger47;
 var init_server = __esm({
   "src/server/index.ts"() {
     "use strict";
@@ -16602,8 +17818,11 @@ var init_server = __esm({
     init_flakiness();
     init_step_library();
     init_recorder2();
+    init_faker2();
+    init_visual_regression();
+    init_ci_integration();
     init_logger();
-    logger46 = createChildLogger("server");
+    logger47 = createChildLogger("server");
   }
 });
 
@@ -16669,7 +17888,21 @@ async function runStudio(options = {}) {
     });
   } catch (err) {
     spinner.fail("Failed to start server");
-    printError(err instanceof Error ? err.message : String(err));
+    const msg = err instanceof Error ? err.message : String(err);
+    if (msg.includes("EADDRINUSE")) {
+      printError(`Port ${port} is already in use.`);
+      printInfo(
+        `Fix: kill the process using the port, then try again:
+  npx kill-port ${port}
+  npx assuremind studio --port ${port}
+
+Or use a different port:
+  npx assuremind studio --port ${port + 1}
+`
+      );
+    } else {
+      printError(msg);
+    }
     process.exit(1);
   }
 }
@@ -16723,7 +17956,7 @@ function validateRunOptions(options) {
     );
   }
 }
-function formatDuration(ms) {
+function formatDuration2(ms) {
   if (ms < 1e3) return `${ms}ms`;
   if (ms < 6e4) return `${(ms / 1e3).toFixed(1)}s`;
   const m = Math.floor(ms / 6e4);
@@ -16744,7 +17977,7 @@ function statusIcon(status) {
 }
 function printCaseResult(tc, ci) {
   const icon = statusIcon(tc.status);
-  const duration = colors.dim(`(${formatDuration(tc.duration)})`);
+  const duration = colors.dim(`(${formatDuration2(tc.duration)})`);
   process.stdout.write(`    ${icon} ${tc.caseName} ${duration}
 `);
   if (!ci || tc.status === "failed") {
@@ -16771,7 +18004,7 @@ function printCaseResult(tc, ci) {
 }
 function printSuiteResult(suite, ci) {
   const icon = statusIcon(suite.status);
-  const duration = colors.dim(`(${formatDuration(suite.duration)})`);
+  const duration = colors.dim(`(${formatDuration2(suite.duration)})`);
   const browser = colors.dim(`[${suite.browser}]`);
   process.stdout.write(
     `
@@ -16783,7 +18016,7 @@ function printSuiteResult(suite, ci) {
   }
 }
 function printRunSummary(result, ci) {
-  const duration = formatDuration(result.duration);
+  const duration = formatDuration2(result.duration);
   const passedStr = colors.success(`${result.passed} passed`);
   const failedStr = result.failed > 0 ? colors.error(`${result.failed} failed`) : colors.dim("0 failed");
   const skippedStr = result.skipped > 0 ? colors.warn(`${result.skipped} skipped`) : colors.dim("0 skipped");
@@ -16906,14 +18139,14 @@ async function loadStoryText(options) {
     return options.story;
   }
   if (options.storyFile) {
-    const filePath = import_path36.default.resolve(options.storyFile);
-    if (!await import_fs_extra27.default.pathExists(filePath)) {
+    const filePath = import_path40.default.resolve(options.storyFile);
+    if (!await import_fs_extra31.default.pathExists(filePath)) {
       throw new ConfigError(
         `Story file not found: "${filePath}"`,
         "STORY_FILE_NOT_FOUND"
       );
     }
-    return import_fs_extra27.default.readFile(filePath, "utf8");
+    return import_fs_extra31.default.readFile(filePath, "utf8");
   }
   throw new ConfigError(
     'Provide a story with --story "<text>" or --story-file <path>',
@@ -16936,7 +18169,7 @@ async function runGenerate(options) {
     process.exit(1);
   }
   const rootDir = process.cwd();
-  const outputDir = options.output ? import_path36.default.resolve(options.output) : import_path36.default.join(rootDir, "tests");
+  const outputDir = options.output ? import_path40.default.resolve(options.output) : import_path40.default.join(rootDir, "tests");
   printInfo(`Story: ${colors.dim(`${storyText.slice(0, 80)}${storyText.length > 80 ? "\u2026" : ""}`)}`);
   if (options.suite) {
     printInfo(`Suite name: ${options.suite}`);
@@ -16968,8 +18201,8 @@ async function runGenerate(options) {
       suiteName: options.suite
     });
     genSpinner.succeed("Suite generated");
-    const suiteOutputDir = options.output ?? import_path36.default.join(rootDir, "tests");
-    printSuccess(`Test suite created in: ${import_path36.default.relative(rootDir, suiteOutputDir)}`);
+    const suiteOutputDir = options.output ?? import_path40.default.join(rootDir, "tests");
+    printSuccess(`Test suite created in: ${import_path40.default.relative(rootDir, suiteOutputDir)}`);
     printInfo("Open Studio or use the Test Editor to review and generate Playwright code:");
     process.stdout.write(`  ${colors.accent("npx assuremind studio")}
 
@@ -16980,13 +18213,13 @@ async function runGenerate(options) {
     process.exit(1);
   }
 }
-var import_path36, import_fs_extra27;
+var import_path40, import_fs_extra31;
 var init_generate = __esm({
   "src/cli/generate.ts"() {
     "use strict";
     init_cjs_shims();
-    import_path36 = __toESM(require("path"));
-    import_fs_extra27 = __toESM(require("fs-extra"));
+    import_path40 = __toESM(require("path"));
+    import_fs_extra31 = __toESM(require("fs-extra"));
     init_ui();
     init_env();
     init_errors();
@@ -17000,7 +18233,7 @@ __export(validate_exports, {
 });
 async function checkConfig(rootDir, result) {
   printInfo("Checking configuration\u2026");
-  if (!await import_fs_extra28.default.pathExists(import_path37.default.join(rootDir, "autotest.config.json")) && !await import_fs_extra28.default.pathExists(import_path37.default.join(rootDir, "autotest.config.ts"))) {
+  if (!await import_fs_extra32.default.pathExists(import_path41.default.join(rootDir, "autotest.config.json")) && !await import_fs_extra32.default.pathExists(import_path41.default.join(rootDir, "autotest.config.ts"))) {
     printError('  autotest.config.ts not found \u2014 run "npx assuremind init" to create it');
     result.errors++;
     return;
@@ -17016,7 +18249,7 @@ async function checkConfig(rootDir, result) {
 }
 async function checkEnv(result) {
   printInfo("Checking environment\u2026");
-  if (!await import_fs_extra28.default.pathExists(".env")) {
+  if (!await import_fs_extra32.default.pathExists(".env")) {
     printWarn("  .env file not found \u2014 copy .env.example to .env and fill in your API key");
     result.warnings++;
     return;
@@ -17032,8 +18265,8 @@ async function checkEnv(result) {
 }
 async function checkTests(rootDir, result) {
   printInfo("Scanning test files\u2026");
-  const testsDir = import_path37.default.join(rootDir, "tests");
-  if (!await import_fs_extra28.default.pathExists(testsDir)) {
+  const testsDir = import_path41.default.join(rootDir, "tests");
+  if (!await import_fs_extra32.default.pathExists(testsDir)) {
     printWarn("  tests/ directory not found \u2014 no tests to validate");
     result.warnings++;
     return;
@@ -17053,7 +18286,7 @@ async function checkTests(rootDir, result) {
       try {
         await readCase(casePath);
       } catch {
-        printError(`  Invalid: ${import_path37.default.relative(rootDir, casePath)}`);
+        printError(`  Invalid: ${import_path41.default.relative(rootDir, casePath)}`);
         invalidCases++;
         result.errors++;
       }
@@ -17081,7 +18314,7 @@ async function checkVariables(rootDir, result) {
     try {
       await readVariables(file);
     } catch {
-      printError(`  Invalid: ${import_path37.default.relative(rootDir, file)}`);
+      printError(`  Invalid: ${import_path41.default.relative(rootDir, file)}`);
       invalid++;
       result.errors++;
     }
@@ -17118,13 +18351,13 @@ async function runValidate() {
     process.exit(1);
   }
 }
-var import_path37, import_fs_extra28;
+var import_path41, import_fs_extra32;
 var init_validate = __esm({
   "src/cli/validate.ts"() {
     "use strict";
     init_cjs_shims();
-    import_path37 = __toESM(require("path"));
-    import_fs_extra28 = __toESM(require("fs-extra"));
+    import_path41 = __toESM(require("path"));
+    import_fs_extra32 = __toESM(require("fs-extra"));
     init_ui();
     init_config_store();
     init_suite_store();
@@ -17189,7 +18422,7 @@ async function checkPlaywright() {
   }
 }
 async function checkEnvFile() {
-  if (!await import_fs_extra29.default.pathExists(".env")) {
+  if (!await import_fs_extra33.default.pathExists(".env")) {
     return check(
       ".env file",
       false,
@@ -17227,7 +18460,7 @@ async function checkConfig2() {
   }
 }
 async function checkPackageJson() {
-  if (!await import_fs_extra29.default.pathExists("package.json")) {
+  if (!await import_fs_extra33.default.pathExists("package.json")) {
     return check(
       "package.json",
       false,
@@ -17235,7 +18468,7 @@ async function checkPackageJson() {
     );
   }
   try {
-    const pkg2 = await import_fs_extra29.default.readJson("package.json");
+    const pkg2 = await import_fs_extra33.default.readJson("package.json");
     return check("package.json", true, `${pkg2.name ?? "unnamed"} v${pkg2.version ?? "?"}`);
   } catch {
     return check("package.json", false, "Exists but is not valid JSON");
@@ -17315,13 +18548,13 @@ async function runDoctor() {
     process.exit(1);
   }
 }
-var import_child_process6, import_fs_extra29;
+var import_child_process6, import_fs_extra33;
 var init_doctor = __esm({
   "src/cli/doctor.ts"() {
     "use strict";
     init_cjs_shims();
     import_child_process6 = require("child_process");
-    import_fs_extra29 = __toESM(require("fs-extra"));
+    import_fs_extra33 = __toESM(require("fs-extra"));
     init_ui();
     init_env();
     init_config_store();
@@ -17348,7 +18581,7 @@ async function findCaseFilePath(testsDir, caseId) {
   return null;
 }
 async function applyHealToFile(rootDir, event) {
-  const testsDir = import_path38.default.join(rootDir, "tests");
+  const testsDir = import_path42.default.join(rootDir, "tests");
   const casePath = await findCaseFilePath(testsDir, event.caseId);
   if (!casePath) {
     throw new Error(
@@ -17370,7 +18603,7 @@ async function applyHealToFile(rootDir, event) {
   testCase.updatedAt = (/* @__PURE__ */ new Date()).toISOString();
   await writeCase(casePath, testCase);
   printSuccess(
-    `  Updated: ${import_path38.default.relative(rootDir, casePath)} \u203A step "${testCase.steps[stepIdx].instruction}"`
+    `  Updated: ${import_path42.default.relative(rootDir, casePath)} \u203A step "${testCase.steps[stepIdx].instruction}"`
   );
 }
 function ask(rl, question) {
@@ -17512,21 +18745,21 @@ Review the changes and merge if the fixes look correct.
 }
 async function runApplyHealing(options) {
   const rootDir = process.cwd();
-  (0, import_dotenv2.config)({ path: import_path38.default.join(rootDir, ".env") });
+  (0, import_dotenv2.config)({ path: import_path42.default.join(rootDir, ".env") });
   process.stdout.write("\n");
   let events;
   if (options.from) {
-    const reportPath = import_path38.default.resolve(options.from);
-    if (!await import_fs_extra30.default.pathExists(reportPath)) {
+    const reportPath = import_path42.default.resolve(options.from);
+    if (!await import_fs_extra34.default.pathExists(reportPath)) {
       printError(`Healing report not found: ${reportPath}`);
       process.exit(1);
     }
     try {
-      const rawRunId = import_path38.default.basename(reportPath, ".json").replace("healing-report-", "");
+      const rawRunId = import_path42.default.basename(reportPath, ".json").replace("healing-report-", "");
       const report = await readHealingReport(rootDir, rawRunId);
       events = report.events.filter((e) => e.status === "pending");
     } catch {
-      const raw = await import_fs_extra30.default.readJson(reportPath);
+      const raw = await import_fs_extra34.default.readJson(reportPath);
       events = Array.isArray(raw) ? raw.filter((e) => e.status === "pending") : (raw.events ?? []).filter((e) => e.status === "pending");
     }
   } else {
@@ -17555,13 +18788,13 @@ async function runApplyHealing(options) {
     }
   }
 }
-var import_path38, import_fs_extra30, import_readline, import_dotenv2;
+var import_path42, import_fs_extra34, import_readline, import_dotenv2;
 var init_apply_healing = __esm({
   "src/cli/apply-healing.ts"() {
     "use strict";
     init_cjs_shims();
-    import_path38 = __toESM(require("path"));
-    import_fs_extra30 = __toESM(require("fs-extra"));
+    import_path42 = __toESM(require("path"));
+    import_fs_extra34 = __toESM(require("fs-extra"));
     import_readline = __toESM(require("readline"));
     import_dotenv2 = require("dotenv");
     init_healing_store();