@veraxhq/verax 0.1.0

package/src/verax/observe/network-sensor.js

@@ -0,0 +1,173 @@
+/**
+ * WAVE 3: Network Truth Sensor
+ * Monitors network requests, responses, failures via Playwright page events
+ */
+
+export class NetworkSensor {
+  constructor(options = {}) {
+    this.slowThresholdMs = options.slowThresholdMs || 2000;
+    this.windows = new Map(); // windowId -> window state
+    this.nextWindowId = 0;
+  }
+
+  /**
+   * Start monitoring network activity and return a window ID.
+   * Call stopWindow(windowId) to get the summary.
+   */
+  startWindow(page) {
+    const windowId = this.nextWindowId++;
+
+    const state = {
+      id: windowId,
+      startTime: Date.now(),
+      requests: new Map(), // url -> { startTime, endTime, status, failed, duration }
+      failedRequests: [],
+      failedByStatus: {}, // status code -> count
+      unfinishedRequests: new Set(), // urls still pending
+      lastErrors: []
+    };
+
+    // Track all requests
+    const onRequest = (request) => {
+      const url = this.redactUrl(request.url());
+      state.unfinishedRequests.add(url);
+
+      if (!state.requests.has(url)) {
+        state.requests.set(url, {
+          url: url,
+          startTime: Date.now(),
+          endTime: null,
+          status: null,
+          failed: false,
+          duration: 0,
+          count: 0
+        });
+      }
+
+      const reqData = state.requests.get(url);
+      reqData.count = (reqData.count || 0) + 1;
+    };
+
+    // Track responses and failures
+    const onResponse = (response) => {
+      const url = this.redactUrl(response.url());
+      const status = response.status();
+
+      if (state.requests.has(url)) {
+        const reqData = state.requests.get(url);
+        reqData.endTime = Date.now();
+        reqData.status = status;
+        reqData.duration = reqData.endTime - reqData.startTime;
+
+        if (status >= 400) {
+          reqData.failed = true;
+          state.failedRequests.push({ url, status, duration: reqData.duration });
+          state.failedByStatus[status] = (state.failedByStatus[status] || 0) + 1;
+        }
+      }
+
+      state.unfinishedRequests.delete(url);
+    };
+
+    const onRequestFailed = (request) => {
+      const url = this.redactUrl(request.url());
+
+      if (state.requests.has(url)) {
+        const reqData = state.requests.get(url);
+        reqData.endTime = Date.now();
+        reqData.duration = reqData.endTime - reqData.startTime;
+        reqData.failed = true;
+      }
+
+      state.failedRequests.push({ url, status: 'FAILED', duration: 0 });
+      state.unfinishedRequests.delete(url);
+    };
+
+    page.on('request', onRequest);
+    page.on('response', onResponse);
+    page.on('requestfailed', onRequestFailed);
+
+    state.cleanup = () => {
+      page.removeListener('request', onRequest);
+      page.removeListener('response', onResponse);
+      page.removeListener('requestfailed', onRequestFailed);
+    };
+
+    this.windows.set(windowId, state);
+    return windowId;
+  }
+
+  /**
+   * Stop monitoring and return a summary for the window.
+   */
+  stopWindow(windowId) {
+    const state = this.windows.get(windowId);
+    if (!state) {
+      return this.getEmptySummary();
+    }
+
+    state.cleanup();
+
+    const endTime = Date.now();
+    const duration = endTime - state.startTime;
+
+    // Find slow requests
+    const slowRequests = Array.from(state.requests.values())
+      .filter((r) => r.duration > this.slowThresholdMs)
+      .sort((a, b) => b.duration - a.duration)
+      .slice(0, 5);
+
+    // Get top failed URLs (limit to 5)
+    const topFailedUrls = state.failedRequests
+      .slice(0, 5)
+      .map((f) => ({ url: f.url, status: f.status, duration: f.duration }));
+
+    const summary = {
+      windowId,
+      totalRequests: state.requests.size,
+      failedRequests: state.failedRequests.length,
+      failedByStatus: state.failedByStatus,
+      hasNetworkActivity: state.requests.size > 0,
+      slowRequestsCount: slowRequests.length,
+      slowRequests: slowRequests.map((r) => ({
+        url: r.url,
+        duration: r.duration
+      })),
+      topFailedUrls: topFailedUrls,
+      duration: duration,
+      unfinishedCount: state.unfinishedRequests.size
+    };
+
+    this.windows.delete(windowId);
+    return summary;
+  }
+
+  /**
+   * Redact query strings from URLs to reduce noise.
+   */
+  redactUrl(url) {
+    try {
+      const parsed = new URL(url);
+      // Keep only scheme + host + pathname, drop query
+      return `${parsed.protocol}//${parsed.host}${parsed.pathname}`;
+    } catch {
+      // If URL parsing fails, return as-is with first 100 chars
+      return url.slice(0, 100);
+    }
+  }
+
+  getEmptySummary() {
+    return {
+      windowId: -1,
+      totalRequests: 0,
+      failedRequests: 0,
+      failedByStatus: {},
+      hasNetworkActivity: false,
+      slowRequestsCount: 0,
+      slowRequests: [],
+      topFailedUrls: [],
+      duration: 0,
+      unfinishedCount: 0
+    };
+  }
+}

package/src/verax/observe/selector-generator.js

@@ -0,0 +1,74 @@
+export async function generateSelector(locator) {
+  try {
+    const element = await locator.elementHandle();
+    if (!element) return 'unknown';
+    
+    const id = await element.getAttribute('id');
+    if (id && id.trim()) {
+      return `#${id.trim()}`;
+    }
+    
+    const dataTestId = await element.getAttribute('data-testid');
+    if (dataTestId && dataTestId.trim()) {
+      return `[data-testid="${dataTestId.trim()}"]`;
+    }
+    
+    const name = await element.getAttribute('name');
+    if (name && name.trim()) {
+      const tag = await element.evaluate(el => el.tagName.toLowerCase());
+      return `${tag}[name="${name.trim()}"]`;
+    }
+    
+    const ariaLabel = await element.getAttribute('aria-label');
+    if (ariaLabel && ariaLabel.trim()) {
+      const tag = await element.evaluate(el => el.tagName.toLowerCase());
+      return `${tag}[aria-label="${ariaLabel.trim()}"]`;
+    }
+    
+    const tag = await element.evaluate(el => el.tagName.toLowerCase());
+    const parent = await element.evaluateHandle(el => el.parentElement);
+    
+    if (parent && !parent.isDisposed()) {
+      const parentTag = await parent.evaluate(el => el.tagName.toLowerCase());
+      const parentId = await parent.getAttribute('id');
+      
+      if (parentId && parentId.trim()) {
+        const siblings = await element.evaluate((el, t) => {
+          const parent = el.parentElement;
+          if (!parent) return 0;
+          const children = Array.from(parent.children);
+          return children.filter(c => c.tagName.toLowerCase() === t).indexOf(el);
+        }, tag);
+        
+        if (siblings > 0) {
+          return `#${parentId.trim()} > ${tag}:nth-of-type(${siblings + 1})`;
+        }
+        return `#${parentId.trim()} > ${tag}`;
+      }
+      
+      if (parentTag) {
+        const siblings = await element.evaluate((el, t) => {
+          const parent = el.parentElement;
+          if (!parent) return 0;
+          const children = Array.from(parent.children);
+          return children.filter(c => c.tagName.toLowerCase() === t).indexOf(el);
+        }, tag);
+        
+        if (siblings > 0) {
+          return `${parentTag} > ${tag}:nth-of-type(${siblings + 1})`;
+        }
+      }
+    }
+    
+    const classes = await element.getAttribute('class');
+    if (classes && classes.trim()) {
+      const classList = classes.trim().split(/\s+/).filter(c => c).slice(0, 3).join('.');
+      return `${tag}.${classList}`;
+    }
+    
+    return tag;
+  } catch (error) {
+    return 'unknown';
+  }
+}
+

package/src/verax/observe/settle.js

@@ -0,0 +1,155 @@
+/**
+ * WAVE 2: Deterministic DOM settle logic
+ * Waits for page to stabilize after navigation or interaction
+ */
+
+/**
+ * Wait for page to settle after navigation or interaction.
+ * Combines multiple signals: load event, network idle, DOM mutation stabilization.
+ *
+ * @param {Page} page - Playwright page object
+ * @param {Object} options
+ * @param {number} options.timeoutMs - Overall timeout (default 30000)
+ * @param {number} options.idleMs - Network idle threshold (default 1500)
+ * @param {number} options.domStableMs - DOM stability window (default 2000)
+ * @returns {Promise<void>}
+ */
+export async function waitForSettle(page, options = {}) {
+  const {
+    timeoutMs = 30000,
+    idleMs = 1500,
+    domStableMs = 2000
+  } = options;
+
+  const startTime = Date.now();
+
+  try {
+    // Signal 1: Wait for load event (DOMContentLoaded or load)
+    await Promise.race([
+      page.waitForLoadState('networkidle', { timeout: timeoutMs }).catch(() => {}),
+      page.waitForLoadState('domcontentloaded', { timeout: timeoutMs }).catch(() => {})
+    ]).catch(() => {});
+
+    // Signal 2: Network idle detection using Playwright Request/Response events
+    await waitForNetworkIdle(page, idleMs, timeoutMs - (Date.now() - startTime));
+
+    // Signal 3: DOM mutation stabilization
+    await waitForDomStability(page, domStableMs, timeoutMs - (Date.now() - startTime));
+  } catch (err) {
+    // Timeout is acceptable - page may have settled despite timeout
+    if (!err.message?.includes('Timeout')) {
+      throw err;
+    }
+  }
+}
+
+/**
+ * Wait for network to become idle (no inflight requests for idleMs).
+ * Uses Playwright's Request/Response event listening.
+ */
+async function waitForNetworkIdle(page, idleMs, timeoutMs) {
+  if (timeoutMs <= 0) return;
+
+  return new Promise((resolve) => {
+    let lastNetworkActivityTime = Date.now();
+    let hasFinished = false;
+
+    const onRequest = () => {
+      lastNetworkActivityTime = Date.now();
+    };
+
+    const onResponse = () => {
+      lastNetworkActivityTime = Date.now();
+    };
+
+    const checkIdle = () => {
+      if (Date.now() - lastNetworkActivityTime >= idleMs) {
+        cleanup();
+        resolve();
+      } else {
+        idleCheckTimer = setTimeout(checkIdle, Math.min(100, idleMs / 2));
+      }
+    };
+
+    const cleanup = () => {
+      if (hasFinished) return;
+      hasFinished = true;
+      page.removeListener('request', onRequest);
+      page.removeListener('response', onResponse);
+      if (idleCheckTimer) clearTimeout(idleCheckTimer);
+      if (timeoutTimer) clearTimeout(timeoutTimer);
+    };
+
+    let idleCheckTimer;
+    const timeoutTimer = setTimeout(() => {
+      cleanup();
+      resolve(); // Timeout resolved, not rejected
+    }, timeoutMs);
+
+    page.on('request', onRequest);
+    page.on('response', onResponse);
+
+    // Start checking after a brief initial wait
+    idleCheckTimer = setTimeout(checkIdle, 100);
+  });
+}
+
+/**
+ * Wait for DOM mutations to stabilize (no mutations for domStableMs).
+ * Uses MutationObserver to track DOM changes.
+ */
+async function waitForDomStability(page, domStableMs, timeoutMs) {
+  if (timeoutMs <= 0) return;
+
+  await page.evaluate(
+    async (domStableMs, timeoutMs) => {
+      return new Promise((resolve) => {
+        let lastMutationTime = Date.now();
+        let hasFinished = false;
+
+        const observer = new MutationObserver(() => {
+          lastMutationTime = Date.now();
+        });
+
+        observer.observe(document.documentElement, {
+          childList: true,
+          subtree: true,
+          attributes: true,
+          attributeFilter: ['class', 'style', 'data-', 'disabled', 'hidden'],
+          characterData: false, // Ignore text changes to reduce noise
+          characterDataOldValue: false
+        });
+
+        const checkStability = () => {
+          if (Date.now() - lastMutationTime >= domStableMs) {
+            cleanup();
+            resolve();
+          } else {
+            stabilityCheckTimer = setTimeout(checkStability, Math.min(100, domStableMs / 2));
+          }
+        };
+
+        const cleanup = () => {
+          if (hasFinished) return;
+          hasFinished = true;
+          observer.disconnect();
+          if (stabilityCheckTimer) clearTimeout(stabilityCheckTimer);
+          if (timeoutTimer) clearTimeout(timeoutTimer);
+        };
+
+        let stabilityCheckTimer;
+        const timeoutTimer = setTimeout(() => {
+          cleanup();
+          resolve(); // Timeout resolved
+        }, timeoutMs);
+
+        // Start checking after a brief initial wait
+        stabilityCheckTimer = setTimeout(checkStability, 100);
+      });
+    },
+    domStableMs,
+    timeoutMs
+  ).catch(() => {
+    // Page may have navigated, ignore
+  });
+}

package/src/verax/observe/state-ui-sensor.js

@@ -0,0 +1,200 @@
+/**
+ * Wave 8 — State UI Sensor
+ *
+ * Detects meaningful UI state changes related to state mutations.
+ * Conservative, accessibility-first signals:
+ * - Dialog/modal visibility (role=dialog, aria-modal)
+ * - Expansion state (aria-expanded)
+ * - Tab selection (role=tab/tabpanel, aria-selected)
+ * - Checkbox/toggle state (aria-checked)
+ * - Alert/status content changes (role=alert/status)
+ * - DOM mutation count (meaningful node additions, not just style/class changes)
+ *
+ * Zero heuristics. Reports exactly what changed.
+ */
+
+export class StateUISensor {
+  /**
+   * Take a snapshot of UI signals related to state mutations.
+   * @param {Object} page - Playwright page object
+   * @param {string|Object} contextSelector - Optional: CSS selector or element handle to focus on
+   * @returns {Promise<Object>} - { signals: {...}, rawSnapshot: {...} }
+   */
+  async snapshot(page, contextSelector = null) {
+    try {
+      const snapshot = await page.evaluate(({ selector }) => {
+        const signals = {};
+        const rawSnapshot = {};
+
+        // 1. Dialog/Modal signals
+        signals.dialogs = [];
+        const dialogs = document.querySelectorAll('[role="dialog"]');
+        for (const dialog of dialogs) {
+          const isVisible = dialog.offsetParent !== null || dialog.hasAttribute('open');
+          const ariaModal = dialog.getAttribute('aria-modal');
+          signals.dialogs.push({
+            visible: isVisible,
+            ariaModal: ariaModal === 'true',
+            hasOpen: dialog.hasAttribute('open')
+          });
+          if (isVisible || ariaModal === 'true') {
+            signals.hasDialog = true;
+          }
+        }
+        rawSnapshot.dialogCount = dialogs.length;
+
+        // 2. Expansion state (aria-expanded)
+        signals.expandedElements = [];
+        const expandables = document.querySelectorAll('[aria-expanded]');
+        for (const el of expandables) {
+          const expanded = el.getAttribute('aria-expanded') === 'true';
+          signals.expandedElements.push({
+            id: el.id || el.className,
+            expanded
+          });
+        }
+        rawSnapshot.expandableCount = expandables.length;
+
+        // 3. Tab selection (role=tab with aria-selected)
+        signals.selectedTabs = [];
+        const tabs = document.querySelectorAll('[role="tab"]');
+        for (const tab of tabs) {
+          const selected = tab.getAttribute('aria-selected') === 'true';
+          signals.selectedTabs.push({
+            id: tab.id || tab.textContent?.substring(0, 20),
+            selected
+          });
+        }
+        rawSnapshot.tabCount = tabs.length;
+
+        // 4. Checkbox/toggle state (aria-checked)
+        signals.checkedElements = [];
+        const checkables = document.querySelectorAll('[aria-checked]');
+        for (const el of checkables) {
+          const checked = el.getAttribute('aria-checked') === 'true';
+          signals.checkedElements.push({
+            id: el.id || el.className,
+            checked
+          });
+        }
+        rawSnapshot.checkableCount = checkables.length;
+
+        // 5. Alert/Status changes (role=alert, role=status)
+        signals.alerts = [];
+        const alerts = document.querySelectorAll('[role="alert"], [role="status"]');
+        for (const alert of alerts) {
+          const text = alert.textContent?.trim() || '';
+          signals.alerts.push({
+            role: alert.getAttribute('role'),
+            text: text.substring(0, 100), // First 100 chars
+            visible: alert.offsetParent !== null
+          });
+        }
+        rawSnapshot.alertCount = alerts.length;
+
+        // 6. DOM mutation count (meaningful changes)
+        // Count visible nodes and text nodes (excluding style/comment nodes)
+        const countMeaningfulNodes = () => {
+          let count = 0;
+          for (const node of document.querySelectorAll('*')) {
+            if (node.offsetParent !== null) { // Visible
+              count++;
+            }
+          }
+          return count;
+        };
+        rawSnapshot.meaningfulNodeCount = countMeaningfulNodes();
+
+        return { signals, rawSnapshot };
+      }, { selector: contextSelector });
+
+      return snapshot;
+    } catch (e) {
+      // If page evaluation fails, return minimal snapshot
+      return {
+        signals: {
+          dialogs: [],
+          expandedElements: [],
+          selectedTabs: [],
+          checkedElements: [],
+          alerts: []
+        },
+        rawSnapshot: {
+          error: e.message
+        }
+      };
+    }
+  }
+
+  /**
+   * Compare two snapshots and report changes.
+   * @param {Object} before - Snapshot from before state mutation
+   * @param {Object} after - Snapshot from after state mutation
+   * @returns {Object} - { changed: boolean, reasons: string[] }
+   */
+  diff(before, after) {
+    const reasons = [];
+
+    if (!before || !after) {
+      return { changed: false, reasons: ['No snapshot data'] };
+    }
+
+    const beforeSignals = before.signals || {};
+    const afterSignals = after.signals || {};
+
+    // Check dialog visibility change
+    const beforeHasDialog = beforeSignals.hasDialog === true;
+    const afterHasDialog = afterSignals.hasDialog === true;
+    if (beforeHasDialog !== afterHasDialog) {
+      reasons.push(afterHasDialog ? 'Dialog opened' : 'Dialog closed');
+    }
+
+    // Check expansion changes
+    const beforeExpanded = this._extractState(beforeSignals.expandedElements || [], 'expanded');
+    const afterExpanded = this._extractState(afterSignals.expandedElements || [], 'expanded');
+    if (beforeExpanded !== afterExpanded) {
+      reasons.push(`Expansion state changed: ${beforeExpanded} → ${afterExpanded}`);
+    }
+
+    // Check tab selection changes
+    const beforeSelected = this._extractState(beforeSignals.selectedTabs || [], 'selected');
+    const afterSelected = this._extractState(afterSignals.selectedTabs || [], 'selected');
+    if (beforeSelected !== afterSelected) {
+      reasons.push(`Tab selection changed: ${beforeSelected} → ${afterSelected}`);
+    }
+
+    // Check checkbox state changes
+    const beforeChecked = this._extractState(beforeSignals.checkedElements || [], 'checked');
+    const afterChecked = this._extractState(afterSignals.checkedElements || [], 'checked');
+    if (beforeChecked !== afterChecked) {
+      reasons.push(`Checked state changed: ${beforeChecked} → ${afterChecked}`);
+    }
+
+    // Check alert changes
+    const beforeAlerts = (beforeSignals.alerts || []).map(a => a.text).join('|');
+    const afterAlerts = (afterSignals.alerts || []).map(a => a.text).join('|');
+    if (beforeAlerts !== afterAlerts) {
+      reasons.push('Alert content changed');
+    }
+
+    // Check DOM mutation (meaningful node count)
+    const beforeNodeCount = before.rawSnapshot?.meaningfulNodeCount || 0;
+    const afterNodeCount = after.rawSnapshot?.meaningfulNodeCount || 0;
+    const nodeDelta = afterNodeCount - beforeNodeCount;
+    if (nodeDelta > 2 || nodeDelta < -2) { // Allow small variance
+      reasons.push(`DOM mutation: ${beforeNodeCount} → ${afterNodeCount} visible nodes`);
+    }
+
+    const changed = reasons.length > 0;
+    return { changed, reasons };
+  }
+
+  /**
+   * Extract state summary from array of elements.
+   * @private
+   */
+  _extractState(elements, key) {
+    if (!elements || elements.length === 0) return '(none)';
+    return elements.map(e => e[key] ? 'T' : 'F').join('');
+  }
+}

package/src/verax/observe/traces-writer.js

@@ -0,0 +1,82 @@
+import { resolve } from 'path';
+import { writeFileSync, mkdirSync } from 'fs';
+import { appendTrace } from '../shared/artifact-manager.js';
+
+export function writeTraces(projectDir, url, traces, coverage = null, warnings = [], artifactPaths = null) {
+  const observation = {
+    version: 1,
+    observedAt: new Date().toISOString(),
+    url: url,
+    traces: traces
+  };
+
+  if (coverage) {
+    observation.coverage = coverage;
+  }
+  if (warnings && warnings.length > 0) {
+    observation.warnings = warnings;
+  }
+  
+  let tracesPath;
+  if (artifactPaths) {
+    // Use new artifact structure
+    // Write JSONL format (one trace per line) for artifact structure
+    traces.forEach(trace => appendTrace(artifactPaths, trace));
+    
+    // Also write full observation JSON for detect() compatibility
+    const jsonPath = resolve(artifactPaths.evidence, 'observation-traces.json');
+    writeFileSync(jsonPath, JSON.stringify(observation, null, 2) + '\n');
+    tracesPath = jsonPath;
+  } else {
+    // Legacy structure
+    const observeDir = resolve(projectDir, '.veraxverax', 'observe');
+    mkdirSync(observeDir, { recursive: true });
+    tracesPath = resolve(observeDir, 'observation-traces.json');
+    writeFileSync(tracesPath, JSON.stringify(observation, null, 2) + '\n');
+  }
+  
+  let externalNavigationBlockedCount = 0;
+  let timeoutsCount = 0;
+  let settleChangedCount = 0;
+  
+  for (const trace of traces) {
+    if (trace.policy) {
+      if (trace.policy.externalNavigationBlocked) {
+        externalNavigationBlockedCount++;
+      }
+      if (trace.policy.timeout) {
+        timeoutsCount++;
+      }
+    }
+
+    if (trace.dom && trace.dom.settle && trace.dom.settle.domChangedDuringSettle) {
+      settleChangedCount++;
+    }
+  }
+  
+  const observeTruth = {
+    interactionsObserved: traces.length,
+    externalNavigationBlockedCount: externalNavigationBlockedCount,
+    timeoutsCount: timeoutsCount,
+    settleChangedCount: settleChangedCount
+  };
+
+  if (coverage) {
+    observeTruth.coverage = coverage;
+    if (coverage.capped) {
+      if (!warnings || warnings.length === 0) {
+        warnings = [{ code: 'INTERACTIONS_CAPPED', message: 'Interaction discovery reached the cap (30). Scan coverage is incomplete.' }];
+      }
+    }
+  }
+  if (warnings && warnings.length > 0) {
+    observeTruth.warnings = warnings;
+  }
+  
+  return {
+    ...observation,
+    tracesPath: tracesPath,
+    observeTruth: observeTruth
+  };
+}
+