@veraxhq/verax 0.1.0

package/src/verax/observe/interaction-discovery.js

@@ -0,0 +1,269 @@
+import { generateSelector } from './selector-generator.js';
+import { isExternalHref } from './domain-boundary.js';
+import { HumanBehaviorDriver } from './human-driver.js';
+
+const MAX_INTERACTIONS_PER_PAGE = 30;
+
+function computePriority(candidate, viewportHeight) {
+  const hasAboveFold = candidate.boundingAvailable && typeof viewportHeight === 'number' && candidate.boundingY < viewportHeight;
+  const isFooter = candidate.boundingAvailable && typeof viewportHeight === 'number' && candidate.boundingY >= viewportHeight;
+  const isInternalLink = candidate.type === 'link' && candidate.href && candidate.href !== '#' && (!candidate.isExternal || candidate.href.startsWith('/'));
+
+  if (candidate.type === 'form') return 1;
+  if (candidate.type === 'link' && isFooter) return 6;
+  if (isInternalLink) return 2;
+  if (candidate.type === 'button' && (candidate.dataHref || (candidate.isRoleButton && (candidate.id || candidate.dataTestId)))) return 3;
+  if (hasAboveFold) return 4;
+  if (candidate.type === 'button') return 5;
+  if (isFooter) return 6;
+  return 7;
+}
+
+function sortCandidates(candidates) {
+  return candidates.sort((a, b) => {
+    if (a.priority !== b.priority) {
+      return a.priority - b.priority;
+    }
+    const selectorCompare = (a.selector || '').localeCompare(b.selector || '');
+    if (selectorCompare !== 0) return selectorCompare;
+    return (a.label || '').localeCompare(b.label || '');
+  });
+}
+
+async function isLanguageToggle(elementHandle) {
+  if (!elementHandle) return false;
+  
+  try {
+    const text = await elementHandle.evaluate(el => el.textContent?.trim() || '');
+    const label = await elementHandle.evaluate(el => el.getAttribute('aria-label') || '');
+    const combined = (text + ' ' + label).toLowerCase();
+    
+    const languagePatterns = [
+      /^(en|de|fr|es|it|pt|ru|zh|ja|ko|ar|he)$/i,
+      /\blanguage\b/i,
+      /\blang\b/i
+    ];
+    
+    return languagePatterns.some(pattern => pattern.test(combined));
+  } catch (error) {
+    return false;
+  }
+}
+
+async function extractLabel(element) {
+  try {
+    const innerText = await element.evaluate(el => el.innerText?.trim() || '');
+    if (innerText) return innerText.substring(0, 100);
+    
+    const ariaLabel = await element.getAttribute('aria-label');
+    if (ariaLabel && ariaLabel.trim()) return ariaLabel.trim().substring(0, 100);
+    
+    const title = await element.getAttribute('title');
+    if (title && title.trim()) return title.trim().substring(0, 100);
+    
+    return '';
+  } catch (error) {
+    return '';
+  }
+}
+
+export async function discoverInteractions(page, baseOrigin) {
+  // Wave 2: Apply scrolling before discovery to reveal lazy-loaded elements
+  const driver = new HumanBehaviorDriver({ maxScrollSteps: 5 });
+  await driver.discoverInteractionsWithScroll(page);
+  
+  // Now run the full discovery with all elements visible
+  const currentUrl = page.url();
+  const interactions = [];
+  const seenElements = new Set();
+  
+  const allInteractions = [];
+  
+  const links = await page.locator('a[href]').all();
+  for (const link of links) {
+    const href = await link.getAttribute('href');
+    if (href && !href.startsWith('#') && !href.startsWith('javascript:')) {
+      const isExternal = isExternalHref(href, baseOrigin, currentUrl);
+      const selector = await generateSelector(link);
+      const selectorKey = `link:${selector}`;
+      
+      if (!seenElements.has(selectorKey)) {
+        seenElements.add(selectorKey);
+        const label = await extractLabel(link);
+        const tagName = await link.evaluate(el => el.tagName.toLowerCase());
+        const id = await link.getAttribute('id');
+        const text = await link.evaluate(el => el.textContent?.trim() || '');
+        
+        allInteractions.push({
+          type: 'link',
+          selector: selector,
+          label: label,
+          element: link,
+          tagName: tagName,
+          id: id || '',
+          text: text,
+          isExternal: isExternal,
+          href: href
+        });
+      }
+    }
+  }
+  
+  const buttons = await page.locator('button:not([disabled])').all();
+  for (const button of buttons) {
+    const selector = await generateSelector(button);
+    const selectorKey = `button:${selector}`;
+    
+    if (!seenElements.has(selectorKey)) {
+      seenElements.add(selectorKey);
+      const label = await extractLabel(button);
+      const elementHandle = await button.elementHandle();
+      const isLangToggle = elementHandle ? await isLanguageToggle(elementHandle) : false;
+      const tagName = await button.evaluate(el => el.tagName.toLowerCase());
+      const id = await button.getAttribute('id');
+      const text = await button.evaluate(el => el.textContent?.trim() || '');
+      const dataHref = await button.getAttribute('data-href');
+      const dataTestId = await button.getAttribute('data-testid');
+      
+      allInteractions.push({
+        type: isLangToggle ? 'toggle' : 'button',
+        selector: selector,
+        label: label,
+        element: button,
+        tagName: tagName,
+        id: id || '',
+        text: text,
+        dataHref: dataHref || '',
+        dataTestId: dataTestId || '',
+        isRoleButton: false
+      });
+    }
+  }
+  
+  const submitInputs = await page.locator('input[type="submit"]:not([disabled]), input[type="button"]:not([disabled])').all();
+  for (const input of submitInputs) {
+    const selector = await generateSelector(input);
+    const selectorKey = `input:${selector}`;
+    
+    if (!seenElements.has(selectorKey)) {
+      seenElements.add(selectorKey);
+      const label = await extractLabel(input);
+      const tagName = await input.evaluate(el => el.tagName.toLowerCase());
+      const id = await input.getAttribute('id');
+      const text = await input.getAttribute('value') || '';
+      const dataHref = await input.getAttribute('data-href');
+      const dataTestId = await input.getAttribute('data-testid');
+      
+      allInteractions.push({
+        type: 'button',
+        selector: selector,
+        label: label || text,
+        element: input,
+        tagName: tagName,
+        id: id || '',
+        text: text,
+        dataHref: dataHref || '',
+        dataTestId: dataTestId || '',
+        isRoleButton: false
+      });
+    }
+  }
+  
+  const roleButtons = await page.locator('[role="button"]:not([disabled])').all();
+  for (const roleButton of roleButtons) {
+    const selector = await generateSelector(roleButton);
+    const selectorKey = `role-button:${selector}`;
+    
+    if (!seenElements.has(selectorKey)) {
+      seenElements.add(selectorKey);
+      const label = await extractLabel(roleButton);
+      const tagName = await roleButton.evaluate(el => el.tagName.toLowerCase());
+      const id = await roleButton.getAttribute('id');
+      const text = await roleButton.evaluate(el => el.textContent?.trim() || '');
+      const dataHref = await roleButton.getAttribute('data-href');
+      const dataTestId = await roleButton.getAttribute('data-testid');
+      
+      allInteractions.push({
+        type: 'button',
+        selector: selector,
+        label: label,
+        element: roleButton,
+        tagName: tagName,
+        id: id || '',
+        text: text,
+        dataHref: dataHref || '',
+        dataTestId: dataTestId || '',
+        isRoleButton: true
+      });
+    }
+  }
+  
+  const forms = await page.locator('form').all();
+  for (const form of forms) {
+    const submitButton = form.locator('button[type="submit"], input[type="submit"]').first();
+    if (await submitButton.count() > 0) {
+      const selector = await generateSelector(submitButton);
+      const selectorKey = `form:${selector}`;
+      
+      if (!seenElements.has(selectorKey)) {
+        seenElements.add(selectorKey);
+        const label = await extractLabel(submitButton);
+        const tagName = await submitButton.evaluate(el => el.tagName.toLowerCase());
+        const id = await submitButton.getAttribute('id');
+        const text = await submitButton.evaluate(el => el.textContent?.trim() || el.getAttribute('value') || '');
+        
+        allInteractions.push({
+          type: 'form',
+          selector: selector,
+          label: label || text,
+          element: submitButton,
+          tagName: tagName,
+          id: id || '',
+          text: text,
+          dataHref: '',
+          dataTestId: '',
+          isRoleButton: false
+        });
+      }
+    }
+  }
+
+  const viewport = page.viewportSize();
+  const viewportHeight = viewport ? viewport.height : undefined;
+
+  for (const item of allInteractions) {
+    try {
+      const box = await item.element.boundingBox();
+      if (box) {
+        item.boundingY = box.y;
+        item.boundingAvailable = true;
+      }
+    } catch (error) {
+      item.boundingAvailable = false;
+    }
+    item.priority = computePriority(item, viewportHeight);
+  }
+
+  const sorted = sortCandidates(allInteractions);
+  const capped = sorted.length > MAX_INTERACTIONS_PER_PAGE;
+  const selected = sorted.slice(0, MAX_INTERACTIONS_PER_PAGE);
+
+  const coverage = {
+    candidatesDiscovered: sorted.length,
+    candidatesSelected: selected.length,
+    cap: MAX_INTERACTIONS_PER_PAGE,
+    capped
+  };
+  
+  return {
+    interactions: selected.map(item => ({
+      type: item.type,
+      selector: item.selector,
+      label: item.label,
+      element: item.element,
+      isExternal: item.isExternal || false
+    })),
+    coverage
+  };
+}
+

package/src/verax/observe/interaction-runner.js

@@ -0,0 +1,410 @@
+import { resolve } from 'path';
+import { captureScreenshot } from './evidence-capture.js';
+import { isExternalUrl } from './domain-boundary.js';
+import { captureDomSignature } from './dom-signature.js';
+import { waitForSettle } from './settle.js';
+import { NetworkSensor } from './network-sensor.js';
+import { ConsoleSensor } from './console-sensor.js';
+import { UISignalSensor } from './ui-signal-sensor.js';
+import { StateUISensor } from './state-ui-sensor.js';
+
+const INTERACTION_TIMEOUT_MS = 10000;
+const NAVIGATION_TIMEOUT_MS = 15000;
+const STABILIZATION_SAMPLE_MID_MS = 500;
+const STABILIZATION_SAMPLE_END_MS = 1500;
+
+// Runtime truth sensors for silent failure detection
+const networkSensor = new NetworkSensor();
+const consoleSensor = new ConsoleSensor();
+const uiSignalSensor = new UISignalSensor();
+const stateUISensor = new StateUISensor();
+
+function markTimeoutPolicy(trace, phase) {
+  trace.policy = {
+    ...(trace.policy || {}),
+    timeout: true,
+    reason: 'interaction_timeout',
+    phase
+  };
+}
+
+function computeDomChangedDuringSettle(samples) {
+  if (!samples || samples.length < 3) {
+    return false;
+  }
+  return samples[0] !== samples[1] || samples[1] !== samples[2];
+}
+
+async function captureSettledDom(page) {
+  const samples = [];
+
+  const sampleDom = async () => {
+    const hash = await captureDomSignature(page);
+    samples.push(hash);
+  };
+
+  await sampleDom();
+  await page.waitForTimeout(STABILIZATION_SAMPLE_MID_MS);
+  await sampleDom();
+  await page.waitForTimeout(STABILIZATION_SAMPLE_END_MS - STABILIZATION_SAMPLE_MID_MS);
+  await sampleDom();
+
+  const domChangedDuringSettle = computeDomChangedDuringSettle(samples);
+
+  return {
+    samples,
+    domChangedDuringSettle,
+    afterHash: samples[samples.length - 1]
+  };
+}
+
+export async function runInteraction(page, interaction, timestamp, i, screenshotsDir, baseOrigin, startTime, maxDurationMs) {
+  const trace = {
+    interaction: {
+      type: interaction.type,
+      selector: interaction.selector,
+      label: interaction.label
+    },
+    before: {
+      url: '',
+      screenshot: ''
+    },
+    after: {
+      url: '',
+      screenshot: ''
+    }
+  };
+  
+  // Declare window IDs outside try block so they're available in catch
+  let networkWindowId = null;
+  let consoleWindowId = null;
+  let uiSignalsBefore = null;
+  let stateUiBefore = null;
+  
+  try {
+    if (Date.now() - startTime > maxDurationMs) {
+      trace.policy = { timeout: true, reason: 'max_scan_duration_exceeded' };
+      return trace;
+    }
+    
+    const beforeUrl = page.url();
+    const beforeScreenshot = resolve(screenshotsDir, `before-${timestamp}-${i}.png`);
+    await captureScreenshot(page, beforeScreenshot);
+    const beforeDomHash = await captureDomSignature(page);
+    
+    // Capture UI signals before interaction
+    try {
+      uiSignalsBefore = await uiSignalSensor.snapshot(page);
+    } catch (e) {
+      // If snapshot fails (e.g., page mock incomplete), use empty object
+      uiSignalsBefore = {
+        hasLoadingIndicator: false,
+        hasDialog: false,
+        hasErrorSignal: false,
+        explanation: []
+      };
+    }
+
+    // Capture state UI signals before interaction (Wave 8)
+    try {
+      stateUiBefore = await stateUISensor.snapshot(page);
+    } catch (e) {
+      // If snapshot fails, use empty object
+      stateUiBefore = {
+        signals: {
+          dialogs: [],
+          expandedElements: [],
+          selectedTabs: [],
+          checkedElements: [],
+          alerts: []
+        },
+        rawSnapshot: {}
+      };
+    }
+    
+    trace.before.url = beforeUrl;
+    trace.before.screenshot = `screenshots/before-${timestamp}-${i}.png`;
+    if (beforeDomHash) {
+      trace.dom = { beforeHash: beforeDomHash };
+    }
+   
+     // Capture sourceRef and handlerRef if present (Wave 5/6 — Action Contracts)
+     let sourceRef = null;
+     let handlerRef = null;
+     try {
+       sourceRef = await interaction.element.getAttribute('data-verax-source');
+     } catch (e) {
+       // Element may not have the attribute
+     }
+     try {
+       handlerRef = await interaction.element.getAttribute('data-verax-handler');
+     } catch (e) {
+       // Element may not have the attribute
+     }
+     if (sourceRef || handlerRef) {
+       trace.meta = {
+         ...(trace.meta || {}),
+         ...(sourceRef ? { sourceRef } : {}),
+         ...(handlerRef ? { handlerRef } : {})
+       };
+     }
+    
+    // Initialize sensors for this interaction
+    try {
+      networkWindowId = networkSensor.startWindow(page);
+      consoleWindowId = consoleSensor.startWindow(page);
+    } catch (e) {
+      // If sensors fail to initialize (e.g., in test environments with incomplete mocks),
+      // continue without them - they'll be gracefully handled with null checks
+      networkWindowId = null;
+      consoleWindowId = null;
+    }
+    
+    if (interaction.isExternal && interaction.type === 'link') {
+      const href = await interaction.element.getAttribute('href');
+      const resolvedUrl = href.startsWith('http') ? href : new URL(href, beforeUrl).href;
+      
+      trace.policy = {
+        externalNavigationBlocked: true,
+        blockedUrl: resolvedUrl
+      };
+      
+      // Stop sensors even on external navigation
+      let networkSummary = null;
+      let consoleSummary = null;
+      if (networkWindowId !== null) {
+        networkSummary = networkSensor.stopWindow(networkWindowId);
+      }
+      if (consoleWindowId !== null) {
+        consoleSummary = consoleSensor.stopWindow(consoleWindowId, page);
+      }
+      
+      const { settleResult, afterUrl } = await captureAfterState(page, screenshotsDir, timestamp, i, trace);
+      trace.after.url = afterUrl;
+      trace.after.screenshot = `screenshots/after-${timestamp}-${i}.png`;
+      if (!trace.dom) {
+        trace.dom = {};
+      }
+      if (settleResult.afterHash) {
+        trace.dom.afterHash = settleResult.afterHash;
+      }
+      trace.dom.settle = {
+        samples: settleResult.samples,
+        domChangedDuringSettle: settleResult.domChangedDuringSettle
+      };
+      
+      // Add sensor evidence to trace
+      trace.sensors = {
+        network: networkSummary,
+        console: consoleSummary
+      };
+      
+      return trace;
+    }
+
+    const clickPromise = interaction.element.click({ timeout: INTERACTION_TIMEOUT_MS });
+    const shouldWaitForNavigation = interaction.type === 'link' || interaction.type === 'form';
+    const navigationPromise = shouldWaitForNavigation
+      ? page.waitForNavigation({ timeout: NAVIGATION_TIMEOUT_MS, waitUntil: 'domcontentloaded' })
+          .catch((error) => {
+            if (error && error.name === 'TimeoutError') {
+              markTimeoutPolicy(trace, 'navigation');
+            }
+            return null;
+          })
+      : null;
+
+    try {
+      await Promise.race([
+        clickPromise,
+        new Promise((_, reject) => setTimeout(() => reject(new Error('timeout')),
+          INTERACTION_TIMEOUT_MS))
+      ]);
+    } catch (error) {
+      if (error.message === 'timeout' || error.name === 'TimeoutError') {
+        // Stop sensors on timeout
+        if (networkWindowId !== null) {
+          networkSensor.stopWindow(networkWindowId);
+        }
+        if (consoleWindowId !== null) {
+          consoleSensor.stopWindow(consoleWindowId, page);
+        }
+        
+        markTimeoutPolicy(trace, 'click');
+        await captureAfterOnly(page, screenshotsDir, timestamp, i, trace);
+        return trace;
+      }
+      throw error;
+    }
+
+    const navigationResult = navigationPromise ? await navigationPromise : null;
+
+    if (navigationResult) {
+      const afterUrl = page.url();
+      if (isExternalUrl(afterUrl, baseOrigin)) {
+        await page.goBack({ timeout: NAVIGATION_TIMEOUT_MS }).catch(() => {});
+        trace.policy = {
+          ...(trace.policy || {}),
+          externalNavigationBlocked: true,
+          blockedUrl: afterUrl
+        };
+      }
+    }
+
+    const { settleResult, afterUrl } = await captureAfterState(page, screenshotsDir, timestamp, i, trace);
+    
+    // Stop sensors after interaction settled
+    const networkSummary = networkWindowId !== null ? networkSensor.stopWindow(networkWindowId) : null;
+    const consoleSummary = consoleWindowId !== null ? consoleSensor.stopWindow(consoleWindowId, page) : null;
+    let uiSignalsAfter = null;
+    let uiSignalChanges = null;
+    let stateUIAfter = null;
+    let stateUIChanges = null;
+    try {
+      uiSignalsAfter = await uiSignalSensor.snapshot(page);
+      uiSignalChanges = uiSignalSensor.diff(uiSignalsBefore, uiSignalsAfter);
+    } catch (e) {
+      // If snapshot fails, use empty objects
+      uiSignalsAfter = {
+        hasLoadingIndicator: false,
+        hasDialog: false,
+        hasErrorSignal: false,
+        explanation: []
+      };
+      uiSignalChanges = { changed: false, explanation: '', summary: [] };
+    }
+
+    // Capture state UI after interaction (Wave 8)
+    try {
+      stateUIAfter = await stateUISensor.snapshot(page);
+      stateUIChanges = stateUISensor.diff(stateUiBefore, stateUIAfter);
+    } catch (e) {
+      stateUIAfter = {
+        signals: {
+          dialogs: [],
+          expandedElements: [],
+          selectedTabs: [],
+          checkedElements: [],
+          alerts: []
+        },
+        rawSnapshot: {}
+      };
+      stateUIChanges = { changed: false, reasons: [] };
+    }
+    
+    trace.after.url = afterUrl;
+    trace.after.screenshot = `screenshots/after-${timestamp}-${i}.png`;
+    if (!trace.dom) {
+      trace.dom = {};
+    }
+    if (settleResult.afterHash) {
+      trace.dom.afterHash = settleResult.afterHash;
+    }
+    trace.dom.settle = {
+      samples: settleResult.samples,
+      domChangedDuringSettle: settleResult.domChangedDuringSettle
+    };
+    
+    // Add sensor evidence to trace
+    trace.sensors = {
+      network: networkSummary,
+      console: consoleSummary,
+      uiSignals: {
+        before: uiSignalsBefore,
+        after: uiSignalsAfter,
+        changes: uiSignalChanges
+      },
+      stateUI: {
+        before: stateUiBefore,
+        after: stateUIAfter,
+        changed: stateUIChanges.changed,
+        reasons: stateUIChanges.reasons
+      }
+    };
+
+    return trace;
+  } catch (error) {
+    if (error.message === 'timeout' || error.name === 'TimeoutError') {
+      // Stop sensors on timeout
+      if (networkWindowId !== null) {
+        try {
+          networkSensor.stopWindow(networkWindowId);
+        } catch (e) {
+          // Ignore sensor cleanup errors
+        }
+      }
+      if (consoleWindowId !== null) {
+        try {
+          consoleSensor.stopWindow(consoleWindowId, page);
+        } catch (e) {
+          // Ignore sensor cleanup errors
+        }
+      }
+      markTimeoutPolicy(trace, 'click');
+      await captureAfterOnly(page, screenshotsDir, timestamp, i, trace);
+      return trace;
+    }
+
+    // Stop sensors on unexpected error
+    if (networkWindowId !== null) {
+      try {
+        networkSensor.stopWindow(networkWindowId);
+      } catch (e) {
+        // Ignore sensor cleanup errors
+      }
+    }
+    if (consoleWindowId !== null) {
+      try {
+        consoleSensor.stopWindow(consoleWindowId, page);
+      } catch (e) {
+        // Ignore sensor cleanup errors
+      }
+    }
+    return null;
+  }
+}
+
+async function captureAfterState(page, screenshotsDir, timestamp, interactionIndex, trace) {
+  // Note: We don't call waitForSettle here because captureSettledDom does its own
+  // sampling to capture async updates. Calling waitForSettle would interfere.
+  
+  let settleResult = {
+    samples: [],
+    domChangedDuringSettle: false,
+    afterHash: null
+  };
+
+  try {
+    settleResult = await captureSettledDom(page);
+  } catch (error) {
+    if (error.message === 'timeout' || error.name === 'TimeoutError') {
+      markTimeoutPolicy(trace, 'settle');
+    }
+  }
+
+  const afterUrl = page.url();
+  const afterScreenshot = resolve(screenshotsDir, `after-${timestamp}-${interactionIndex}.png`);
+  await captureScreenshot(page, afterScreenshot);
+
+  return { settleResult, afterUrl };
+}
+
+async function captureAfterOnly(page, screenshotsDir, timestamp, interactionIndex, trace) {
+  const afterUrl = page.url();
+  const afterScreenshot = resolve(screenshotsDir, `after-${timestamp}-${interactionIndex}.png`);
+  try {
+    await captureScreenshot(page, afterScreenshot);
+    const afterDomHash = await captureDomSignature(page);
+    trace.after.url = afterUrl;
+    trace.after.screenshot = `screenshots/after-${timestamp}-${interactionIndex}.png`;
+    if (afterDomHash) {
+      if (!trace.dom) {
+        trace.dom = {};
+      }
+      trace.dom.afterHash = afterDomHash;
+    }
+  } catch (e) {
+    // Ignore screenshot errors on timeout
+  }
+}
+