@zibby/core 0.1.21 → 0.1.22

package/src/enrichment/enrichers/dom-enricher.js

@@ -1,171 +0,0 @@
-/**
- * DOM Enricher - Captures DOM path, XPath, and element attributes
- * This file contains browser code executed via element.evaluate() where browser globals are available
- */
-/* global document, window */
-import { EventEnricher } from '../base.js';
-
-export class DOMEnricher extends EventEnricher {
-  getName() {
-    return 'DOMEnricher';
-  }
-
-  getPriority() {
-    return 85; // High priority - structural data
-  }
-
-  canEnrich(context) {
-    if (!this.enabled) return false;
-    if (!context.element) return false;
-    if (!context.event) return false;
-    
-    return ['click', 'fill', 'type', 'selectOption', 'hover'].includes(context.event.type);
-  }
-
-  async enrich(event, context) {
-    try {
-      const { element } = context;
-      
-      // Get DOM path, XPath, and attributes
-      const domData = await element.evaluate(el => {
-        // Build CSS path
-        const getCssPath = (innerEl) => {
-          const path = [];
-          let current = innerEl;
-          
-          while (current && current !== document.body) {
-            let selector = current.tagName.toLowerCase();
-            
-            // Add nth-child if there are siblings of same type
-            const parent = current.parentElement;
-            if (parent) {
-              const siblings = Array.from(parent.children).filter(
-                child => child.tagName === current.tagName
-              );
-              if (siblings.length > 1) {
-                const index = siblings.indexOf(current) + 1;
-                selector += `:nth-child(${index})`;
-              }
-            }
-            
-            path.unshift(selector);
-            current = current.parentElement;
-          }
-          
-          return `body > ${path.join(' > ')}`;
-        };
-        
-        // Build XPath
-        const getXPath = (innerEl) => {
-          const path = [];
-          let current = innerEl;
-          
-          while (current && current !== document.body) {
-            let index = 1;
-            let sibling = current.previousSibling;
-            
-            while (sibling) {
-              if (sibling.nodeType === 1 && sibling.tagName === current.tagName) {
-                index++;
-              }
-              sibling = sibling.previousSibling;
-            }
-            
-            const tag = current.tagName.toLowerCase();
-            path.unshift(`${tag}[${index}]`);
-            current = current.parentElement;
-          }
-          
-          return `/html/body/${path.join('/')}`;
-        };
-        
-        // Get all attributes
-        const attributes = {};
-        for (const attr of el.attributes) {
-          attributes[attr.name] = attr.value;
-        }
-        
-        // Get computed style (only essential properties)
-        const computed = window.getComputedStyle(el);
-        const state = {
-          display: computed.display,
-          visibility: computed.visibility,
-          opacity: computed.opacity,
-          pointerEvents: computed.pointerEvents
-        };
-        
-        // Calculate depth
-        let depth = 0;
-        let parent = el.parentElement;
-        while (parent) {
-          depth++;
-          parent = parent.parentElement;
-        }
-        
-        return {
-          path: getCssPath(el),
-          xpath: getXPath(el),
-          depth,
-          parent: el.parentElement ? el.parentElement.tagName.toLowerCase() : null,
-          tagName: el.tagName.toLowerCase(),
-          attributes,
-          state: {
-            visible: computed.display !== 'none' && computed.visibility !== 'hidden',
-            enabled: !el.disabled,
-            focused: document.activeElement === el,
-            ...state
-          }
-        };
-      });
-      
-      return {
-        dom: {
-          path: domData.path,
-          xpath: domData.xpath,
-          depth: domData.depth,
-          parent: domData.parent,
-          selector: this.buildSmartSelector(domData)
-        },
-        attributes: domData.attributes,
-        state: domData.state
-      };
-    } catch (error) {
-      return this.handleError(error, event);
-    }
-  }
-
-  /**
-   * Build a smart CSS selector from DOM data
-   */
-  buildSmartSelector(domData) {
-    let selector = domData.tagName;
-    
-    // Add ID if available
-    if (domData.attributes.id) {
-      return `#${domData.attributes.id}`;
-    }
-    
-    // Add data-test-id if available
-    if (domData.attributes['data-test-id']) {
-      return `[data-test-id="${domData.attributes['data-test-id']}"]`;
-    }
-    
-    // Add class if available
-    if (domData.attributes.class) {
-      const classes = domData.attributes.class.split(' ')
-        .filter(c => c && !c.match(/^(active|focus|hover|disabled)/)); // Skip state classes
-      if (classes.length > 0) {
-        selector += `.${classes.slice(0, 2).join('.')}`;
-      }
-    }
-    
-    // Add parent context
-    if (domData.parent) {
-      selector = `${domData.parent} > ${selector}`;
-    }
-    
-    return selector;
-  }
-}
-
-export default DOMEnricher;

package/src/enrichment/enrichers/page-state-enricher.js

@@ -1,129 +0,0 @@
-/**
- * Page State Enricher - Captures network and page stability state
- * This file contains browser code executed via page.evaluate() where browser globals are available
- */
-/* global document, MutationObserver */
-import { EventEnricher } from '../base.js';
-
-export class PageStateEnricher extends EventEnricher {
-  constructor(config = {}) {
-    super(config);
-    this.pendingRequests = new Set();
-    this.setupNetworkTracking = false;
-  }
-
-  getName() {
-    return 'PageStateEnricher';
-  }
-
-  getPriority() {
-    return 95; // Very high priority - critical for timing
-  }
-
-  canEnrich(context) {
-    return this.enabled && context.page;
-  }
-
-  /**
-   * Setup network request tracking (call once per page)
-   */
-  async setupTracking(page) {
-    if (this.setupNetworkTracking) return;
-    
-    page.on('request', (request) => {
-      if (['document', 'xhr', 'fetch'].includes(request.resourceType())) {
-        this.pendingRequests.add(request.url());
-      }
-    });
-    
-    page.on('requestfinished', (request) => {
-      this.pendingRequests.delete(request.url());
-    });
-    
-    page.on('requestfailed', (request) => {
-      this.pendingRequests.delete(request.url());
-    });
-    
-    this.setupNetworkTracking = true;
-  }
-
-  async enrich(event, context) {
-    try {
-      const { page } = context;
-      
-      // Setup tracking if not done
-      await this.setupTracking(page);
-      
-      // Get page load state
-      const pageState = await page.evaluate(() => ({
-        readyState: document.readyState,
-        domContentLoaded: document.readyState !== 'loading',
-        loadComplete: document.readyState === 'complete',
-        url: document.location.href
-      }));
-      
-      // Check if DOM is stable (no mutations for 500ms)
-      const domStable = await this.checkDOMStability(page);
-      
-      return {
-        page: {
-          networkIdle: this.pendingRequests.size === 0,
-          pendingRequests: this.pendingRequests.size,
-          domStable,
-          ...pageState
-        }
-      };
-    } catch (error) {
-      return this.handleError(error, event);
-    }
-  }
-
-  /**
-   * Check if DOM hasn't mutated for 500ms
-   */
-  async checkDOMStability(page, timeoutMs = 500) {
-    try {
-      const stable = await page.evaluate((timeout) => {
-        return new Promise((resolve) => {
-          let timer;
-          let mutations = 0;
-          
-          const observer = new MutationObserver(() => {
-            mutations++;
-            clearTimeout(timer);
-            timer = setTimeout(() => {
-              observer.disconnect();
-              resolve(mutations === 0);
-            }, timeout);
-          });
-          
-          observer.observe(document.body, {
-            childList: true,
-            subtree: true,
-            attributes: true
-          });
-          
-          // Initial timer
-          timer = setTimeout(() => {
-            observer.disconnect();
-            resolve(true);
-          }, timeout);
-        });
-      }, timeoutMs);
-      
-      return stable;
-    } catch (_error) {
-      return false; // Assume not stable on error
-    }
-  }
-
-  /**
-   * Reset tracking for new page navigation
-   */
-  reset() {
-    this.pendingRequests.clear();
-    this.setupNetworkTracking = false;
-  }
-}
-
-export default PageStateEnricher;

package/src/enrichment/enrichers/position-enricher.js

@@ -1,67 +0,0 @@
-/**
- * Position Enricher - Captures element bounding box and viewport state
- * This file contains browser code executed via element.evaluate() where browser globals are available
- */
-/* global window */
-import { EventEnricher } from '../base.js';
-
-export class PositionEnricher extends EventEnricher {
-  getName() {
-    return 'PositionEnricher';
-  }
-
-  getPriority() {
-    return 90; // High priority - cheap and useful
-  }
-
-  canEnrich(context) {
-    // Only enrich interactive actions that have an element
-    if (!this.enabled) return false;
-    if (!context.element) return false;
-    if (!context.event) return false;
-    
-    return ['click', 'fill', 'type', 'selectOption', 'hover'].includes(context.event.type);
-  }
-
-  async enrich(event, context) {
-    try {
-      const { page, element } = context;
-      
-      // Get bounding box
-      const box = await element.boundingBox();
-      if (!box) return null; // Element not visible
-      
-      // Get viewport state
-      const viewport = await page.evaluate(() => ({
-        scrollX: window.scrollX,
-        scrollY: window.scrollY,
-        width: window.innerWidth,
-        height: window.innerHeight
-      }));
-      
-      // Check if in viewport
-      const inViewport = (
-        box.y >= viewport.scrollY &&
-        box.y + box.height <= viewport.scrollY + viewport.height &&
-        box.x >= 0 &&
-        box.x + box.width <= viewport.width
-      );
-      
-      return {
-        position: {
-          boundingBox: box,
-          viewport,
-          inViewport,
-          centerPoint: {
-            x: Math.round(box.x + box.width / 2),
-            y: Math.round(box.y + box.height / 2)
-          }
-        }
-      };
-    } catch (error) {
-      return this.handleError(error, event);
-    }
-  }
-}
-
-export default PositionEnricher;

package/src/enrichment/index.js

@@ -1,96 +0,0 @@
-/**
- * Event Enrichment System
- * Modular pipeline for adding data to MCP events
- */
-
-export { EventEnricher } from './base.js';
-export { EnrichmentPipeline } from './pipeline.js';
-
-// Enrichers
-export { PositionEnricher } from './enrichers/position-enricher.js';
-export { AccessibilityEnricher } from './enrichers/accessibility-enricher.js';
-export { PageStateEnricher } from './enrichers/page-state-enricher.js';
-export { DOMEnricher } from './enrichers/dom-enricher.js';
-export { MCPRefEnricher } from './mcp-ref-enricher.js';
-export { TraceTextEnricher } from './trace-text-enricher.js';
-
-import { EnrichmentPipeline } from './pipeline.js';
-import { PositionEnricher } from './enrichers/position-enricher.js';
-import { AccessibilityEnricher } from './enrichers/accessibility-enricher.js';
-import { PageStateEnricher } from './enrichers/page-state-enricher.js';
-import { DOMEnricher } from './enrichers/dom-enricher.js';
-import { MCPRefEnricher } from './mcp-ref-enricher.js';
-import { TraceTextEnricher } from './trace-text-enricher.js';
-
-/**
- * Create a default enrichment pipeline with all enrichers
- * @param {Object} config - Configuration options
- * @param {boolean} config.enablePosition - Enable position enricher (default: true)
- * @param {boolean} config.enableAccessibility - Enable accessibility enricher (default: true)
- * @param {boolean} config.enablePageState - Enable page state enricher (default: true)
- * @param {boolean} config.enableDOM - Enable DOM enricher (default: true)
- * @returns {EnrichmentPipeline}
- */
-export function createDefaultPipeline(config = {}) {
-  const pipeline = new EnrichmentPipeline(config);
-  
-  // Register enrichers (they'll auto-sort by priority)
-  // MCPRefEnricher has highest priority (200) - captures exact MCP refs
-  if (config.enableMCPRef !== false) {
-    pipeline.register(new MCPRefEnricher(config));
-  }
-  
-  // TraceTextEnricher (190) - extracts ACTUAL text from trace (for Chinese/multi-language)
-  if (config.enableTraceText !== false) {
-    pipeline.register(new TraceTextEnricher(config));
-  }
-  
-  if (config.enableAccessibility !== false) {
-    pipeline.register(new AccessibilityEnricher(config));
-  }
-  
-  if (config.enablePageState !== false) {
-    pipeline.register(new PageStateEnricher(config));
-  }
-  
-  if (config.enablePosition !== false) {
-    pipeline.register(new PositionEnricher(config));
-  }
-  
-  if (config.enableDOM !== false) {
-    pipeline.register(new DOMEnricher(config));
-  }
-  
-  return pipeline;
-}
-
-/**
- * Create a minimal pipeline (only critical enrichers)
- * @param {Object} config
- * @returns {EnrichmentPipeline}
- */
-export function createMinimalPipeline(config = {}) {
-  const pipeline = new EnrichmentPipeline(config);
-  
-  // Only most critical enrichers
-  pipeline.register(new AccessibilityEnricher(config));
-  pipeline.register(new PageStateEnricher(config));
-  
-  return pipeline;
-}
-
-/**
- * Create a custom pipeline
- * @param {Array} enrichers - Array of enricher instances
- * @param {Object} config
- * @returns {EnrichmentPipeline}
- */
-export function createCustomPipeline(enrichers, config = {}) {
-  const pipeline = new EnrichmentPipeline(config);
-  
-  for (const enricher of enrichers) {
-    pipeline.register(enricher);
-  }
-  
-  return pipeline;
-}

package/src/enrichment/mcp-integration.js

@@ -1,149 +0,0 @@
-/**
- * MCP Recorder Integration with Enrichment Pipeline
- * 
- * This module provides utilities to enrich MCP-recorded events
- * after test execution (when we have access to trace data)
- */
-
-import { createDefaultPipeline, createMinimalPipeline } from './index.js';
-import { readFileSync, writeFileSync } from 'fs';
-import { join } from 'path';
-
-/**
- * Enrich recorded events.json file with data from Playwright trace
- * 
- * @param {string} sessionPath - Path to session directory
- * @param {Object} config - Enrichment configuration
- * @returns {Promise<Object>} - { enrichedCount, skippedCount, errors }
- */
-export async function enrichRecordedEvents(sessionPath, _config = {}) {
-  const eventsPath = join(sessionPath, 'events.json');
-  const _tracePath = join(sessionPath, 'trace.zip');
-  
-  try {
-    // Read events
-    const events = JSON.parse(readFileSync(eventsPath, 'utf-8'));
-    
-    // For now, we add placeholder enrichment metadata
-    // Full enrichment requires re-playing with Playwright access
-    const enriched = events.map(event => ({
-      ...event,
-      _enrichmentNote: 'Full enrichment requires live Playwright access. Use EnrichmentPipeline during test execution.'
-    }));
-    
-    // Save enriched events
-    const backupPath = `${eventsPath  }.backup`;
-    writeFileSync(backupPath, JSON.stringify(events, null, 2));
-    writeFileSync(eventsPath, JSON.stringify(enriched, null, 2));
-    
-    return {
-      enrichedCount: enriched.length,
-      skippedCount: 0,
-      errors: []
-    };
-  } catch (error) {
-    console.error('[EnrichmentIntegration] Failed to enrich events:', error.message);
-    return {
-      enrichedCount: 0,
-      skippedCount: 0,
-      errors: [error.message]
-    };
-  }
-}
-
-/**
- * Example: How to use enrichment pipeline during live test execution
- * 
- * This is a reference implementation for integrating enrichment
- * into your test execution flow where you have Playwright access.
- */
-export class LiveEnrichmentRecorder {
-  constructor(config = {}) {
-    // Create enrichment pipeline
-    this.pipeline = config.minimal 
-      ? createMinimalPipeline(config)
-      : createDefaultPipeline(config);
-    
-    this.events = [];
-    this.config = config;
-  }
-
-  /**
-   * Record and enrich an event during test execution
-   * 
-   * @param {string} type - Event type (click, fill, etc)
-   * @param {Object} data - Event data
-   * @param {Object} context - { page, element, ref }
-   * @returns {Promise<Object>} - Enriched event
-   */
-  async recordEvent(type, data, context) {
-    // Create base event (MCP format)
-    const baseEvent = {
-      id: this.events.length,
-      type,
-      timestamp: new Date().toISOString(),
-      data
-    };
-    
-    // Enrich with pipeline
-    const enriched = await this.pipeline.enrich(baseEvent, {
-      ...context,
-      event: baseEvent
-    });
-    
-    this.events.push(enriched);
-    return enriched;
-  }
-
-  /**
-   * Save enriched events to file
-   * @param {string} filePath
-   */
-  saveEvents(filePath) {
-    writeFileSync(filePath, JSON.stringify(this.events, null, 2));
-    console.log(`[LiveEnrichment] Saved ${this.events.length} enriched events to ${filePath}`);
-    
-    // Log statistics
-    this.pipeline.logStatus();
-  }
-
-  /**
-   * Get pipeline statistics
-   */
-  getStats() {
-    return this.pipeline.getStats();
-  }
-}
-
-/**
- * Example integration with Cursor Agent workflow
- * 
- * Usage in execute_live node:
- * 
- * ```javascript
- * import { LiveEnrichmentRecorder } from '@zibby/core';
- * 
- * const recorder = new LiveEnrichmentRecorder({ minimal: true });
- * 
- * // During test execution (when you have page/element access):
- * const page = await browser.newPage();
- * const element = await page.locator('button');
- * 
- * // Record enriched event
- * await recorder.recordEvent('click', {
- *   tool: 'browser_click',
- *   params: { element: 'Submit button', ref: 'k123' }
- * }, {
- *   page,
- *   element
- * });
- * 
- * // Save at end
- * recorder.saveEvents('enriched-events.json');
- * ```
- */
-
-export default {
-  enrichRecordedEvents,
-  LiveEnrichmentRecorder
-};

package/src/enrichment/mcp-ref-enricher.js

@@ -1,78 +0,0 @@
-import { EventEnricher } from './base.js';
-
-/**
- * MCPRefEnricher - Captures ACTUAL element text from trace DOM snapshots
- * 
- * Problem: AI might say "Login button" but actual button text is "登录" (Chinese)
- * Solution: Extract the REAL text from trace DOM snapshot at action time
- * 
- * Priority order:
- * 1. Extract actual text/label from trace DOM snapshot (handles Chinese/any language)
- * 2. Fall back to MCP element description (AI's description)
- * 
- * This ensures Chinese, Arabic, Japanese, etc. apps work perfectly!
- */
-export class MCPRefEnricher extends EventEnricher {
-  constructor(config = {}) {
-    super(config);
-    this.priority = 200; // Highest priority
-  }
-
-  getName() {
-    return 'MCPRef';
-  }
-
-  getPriority() {
-    return this.priority;
-  }
-
-  async enrich(event, context) {
-    const ref = event.data?.params?.ref;
-    const mcpElement = event.data?.params?.element; // What AI said
-    
-    if (!ref && !mcpElement) {
-      return null;
-    }
-
-    // Try to extract ACTUAL element properties from the DOM (if we have element access)
-    let actualText = null;
-    let actualRole = null;
-    let actualLabel = null;
-    
-    if (context?.element) {
-      try {
-        // Extract the REAL text that user sees (not what AI said)
-        const elementData = await context.element.evaluate(el => {
-          return {
-            text: el.textContent?.trim() || '',
-            innerText: el.innerText?.trim() || '',
-            value: el.value || '',
-            label: el.getAttribute('aria-label') || el.getAttribute('label') || '',
-            role: el.getAttribute('role') || el.tagName.toLowerCase(),
-            placeholder: el.getAttribute('placeholder') || '',
-            title: el.getAttribute('title') || ''
-          };
-        });
-        
-        // Use the most specific text we can find
-        actualText = elementData.text || elementData.innerText || elementData.value || elementData.placeholder;
-        actualRole = elementData.role;
-        actualLabel = elementData.label || elementData.title;
-        
-        console.log(`[MCPRefEnricher] ✅ Captured actual text: "${actualText}" (AI said: "${mcpElement}")`);
-      } catch (e) {
-        console.log(`[MCPRefEnricher] ⚠️  Could not extract actual text: ${e.message}`);
-      }
-    }
-
-    return {
-      mcpRef: ref,
-      mcpElement,           // What AI said (might be translated)
-      actualText,            // ✅ REAL text from DOM (Chinese/any language)
-      actualRole,            // ✅ REAL role (button, link, textbox)
-      actualLabel,          // ✅ REAL aria-label
-      // Use actual text if available, otherwise fall back to AI's description
-      recordedSelector: actualText || mcpElement
-    };
-  }
-}