@arclabs561/ai-visual-test 0.5.1

package/src/spec-templates.mjs

@@ -0,0 +1,347 @@
+/**
+ * Natural Language Spec Templates
+ * 
+ * Reusable templates for common testing patterns based on real-world BDD usage.
+ * Supports template inheritance and composition.
+ * 
+ * Based on research findings:
+ * - Real-world BDD patterns (Cucumber, SpecFlow, Behave)
+ * - Real-world usage patterns (200+ tests)
+ * - Best practices (scenario independence, domain language, living documentation)
+ */
+
+import { log } from './logger.mjs';
+
+/**
+ * Built-in templates for common patterns
+ */
+export const TEMPLATES = {
+  /**
+   * Game Testing Template
+   * Based on real-world interactive game patterns
+   */
+  game: {
+    name: 'Game Testing',
+    description: 'Template for testing interactive games with activation keys',
+    spec: `Given I visit {url}
+When I activate the game (press '{activationKey}'{selector})
+Then the game should be playable
+{goals}
+Context: viewport={viewport}, device={device}{temporal}`,
+    variables: {
+      url: 'game.example.com',
+      activationKey: 'g',
+      selector: '',
+      viewport: '1280x720',
+      device: 'desktop',
+      goals: '',
+      temporal: ''
+    },
+    examples: [
+      {
+        name: 'Basic Game',
+        values: {
+          url: 'example.com',
+          activationKey: 'g',
+          selector: ', selector: #game-paddle'
+        }
+      },
+      {
+        name: 'Game with Temporal',
+        values: {
+          url: 'game.example.com',
+          activationKey: 'g',
+          selector: ', selector: #game-element',
+          temporal: ', fps: 2, duration: 10 seconds, temporal: true'
+        }
+      }
+    ]
+  },
+  
+  /**
+   * Accessibility Template
+   */
+  accessibility: {
+    name: 'Accessibility Testing',
+    description: 'Template for accessibility validation',
+    spec: `Given I visit {url}{persona}
+When the page loads
+Then it should be accessible
+{checks}
+Context: viewport={viewport}, device={device}`,
+    variables: {
+      url: 'example.com',
+      persona: '',
+      viewport: '1280x720',
+      device: 'desktop',
+      checks: 'And contrast should meet WCAG standards'
+    },
+    examples: [
+      {
+        name: 'Basic Accessibility',
+        values: {
+          url: 'example.com'
+        }
+      },
+      {
+        name: 'Accessibility with Persona',
+        values: {
+          url: 'example.com',
+          persona: ' as a visually impaired user'
+        }
+      }
+    ]
+  },
+  
+  /**
+   * Browser Experience Template
+   */
+  browser_experience: {
+    name: 'Browser Experience',
+    description: 'Template for complete user journey testing',
+    spec: `Given I visit {url}
+{steps}
+Then {outcome}
+Context: viewport={viewport}, device={device}`,
+    variables: {
+      url: 'example.com',
+      steps: 'When the page loads',
+      outcome: 'the page should be usable',
+      viewport: '1280x720',
+      device: 'desktop'
+    },
+    examples: [
+      {
+        name: 'E-commerce Journey',
+        values: {
+          url: 'shop.example.com',
+          steps: `When I browse products
+And I add items to cart
+And I proceed to checkout`,
+          outcome: 'the checkout form should be usable'
+        }
+      }
+    ]
+  },
+  
+  /**
+   * State Validation Template
+   */
+  state_validation: {
+    name: 'State Validation',
+    description: 'Template for validating state consistency',
+    spec: `Given {initialState}
+When {action}
+Then the state should be consistent
+{checks}
+Context: viewport={viewport}`,
+    variables: {
+      initialState: 'I visit a page',
+      action: 'the state changes',
+      checks: 'And the visual representation should match the internal state',
+      viewport: '1280x720'
+    },
+    examples: [
+      {
+        name: 'Game State',
+        values: {
+          initialState: 'I play a game',
+          action: 'the game state changes',
+          checks: 'And cleared elements should be visually removed'
+        }
+      }
+    ]
+  },
+  
+  /**
+   * Temporal Sequence Template
+   */
+  temporal: {
+    name: 'Temporal Sequence',
+    description: 'Template for testing sequences over time',
+    spec: `Given {initial}
+When I observe {target} for {duration}
+Then {expected}
+Context: fps={fps}, duration={duration} seconds, temporal: true`,
+    variables: {
+      initial: 'I visit a page with animations',
+      target: 'the page',
+      duration: '5',
+      fps: '2',
+      expected: 'animations should be smooth'
+    },
+    examples: [
+      {
+        name: 'Animation Validation',
+        values: {
+          initial: 'I visit a page with animations',
+          target: 'the page',
+          duration: '5',
+          fps: '2',
+          expected: 'animations should be smooth'
+        }
+      }
+    ]
+  },
+  
+  /**
+   * Property-Based Template
+   */
+  property: {
+    name: 'Property-Based Testing',
+    description: 'Template for property/invariant testing',
+    spec: 'For all {scope}, {property}',
+    variables: {
+      scope: 'screenshots',
+      property: 'the validation score should be between 0 and 10'
+    },
+    examples: [
+      {
+        name: 'Score Range',
+        values: {
+          scope: 'screenshots',
+          property: 'the validation score should be between 0 and 10'
+        }
+      },
+      {
+        name: 'State Consistency',
+        values: {
+          scope: 'game states',
+          property: 'the visual representation should match the internal state'
+        }
+      }
+    ]
+  }
+};
+
+/**
+ * Create a spec from a template
+ */
+export function createSpecFromTemplate(templateName, variables = {}) {
+  const template = TEMPLATES[templateName];
+  
+  if (!template) {
+    throw new Error(`Template "${templateName}" not found. Available: ${Object.keys(TEMPLATES).join(', ')}`);
+  }
+  
+  // Merge template variables with provided variables
+  const mergedVars = {
+    ...template.variables,
+    ...variables
+  };
+  
+  // Replace variables in spec
+  let spec = template.spec;
+  for (const [key, value] of Object.entries(mergedVars)) {
+    const placeholder = `{${key}}`;
+    spec = spec.replace(new RegExp(placeholder.replace(/[{}]/g, '\\$&'), 'g'), String(value));
+  }
+  
+  return spec;
+}
+
+/**
+ * Compose multiple templates
+ */
+export function composeTemplates(templates, composition = 'sequential') {
+  if (composition === 'sequential') {
+    // Sequential: execute one after another
+    return templates.map(t => t.spec).join('\n\n');
+  } else if (composition === 'parallel') {
+    // Parallel: execute all (would need execution framework support)
+    return templates.map(t => t.spec).join('\n\n---\n\n');
+  } else {
+    throw new Error(`Unknown composition type: ${composition}`);
+  }
+}
+
+/**
+ * Inherit from a base template
+ */
+export function inheritTemplate(baseTemplateName, overrides = {}) {
+  const base = TEMPLATES[baseTemplateName];
+  
+  if (!base) {
+    throw new Error(`Base template "${baseTemplateName}" not found`);
+  }
+  
+  return {
+    ...base,
+    ...overrides,
+    variables: {
+      ...base.variables,
+      ...(overrides.variables || {})
+    }
+  };
+}
+
+/**
+ * Register a custom template
+ */
+export function registerTemplate(name, template) {
+  if (!template.name || !template.spec || !template.variables) {
+    throw new Error('Template must have name, spec, and variables');
+  }
+  
+  TEMPLATES[name] = template;
+  log(`[SpecTemplates] Registered custom template: ${name}`);
+}
+
+/**
+ * List available templates
+ */
+export function listTemplates() {
+  return Object.keys(TEMPLATES).map(name => ({
+    name,
+    ...TEMPLATES[name]
+  }));
+}
+
+/**
+ * Get template by name
+ */
+export function getTemplate(name) {
+  const template = TEMPLATES[name];
+  
+  if (!template) {
+    throw new Error(`Template "${name}" not found. Available: ${Object.keys(TEMPLATES).join(', ')}`);
+  }
+  
+  return template;
+}
+
+/**
+ * Validate template structure
+ */
+export function validateTemplate(template) {
+  const errors = [];
+  
+  if (!template.name) {
+    errors.push('Template must have a name');
+  }
+  
+  if (!template.spec) {
+    errors.push('Template must have a spec');
+  }
+  
+  if (!template.variables || typeof template.variables !== 'object') {
+    errors.push('Template must have variables object');
+  }
+  
+  // Check that all placeholders in spec have corresponding variables
+  const placeholders = template.spec.match(/\{(\w+)\}/g) || [];
+  const placeholderNames = placeholders.map(p => p.slice(1, -1));
+  const variableNames = Object.keys(template.variables || {});
+  
+  for (const placeholder of placeholderNames) {
+    if (!variableNames.includes(placeholder)) {
+      errors.push(`Placeholder {${placeholder}} in spec has no corresponding variable`);
+    }
+  }
+  
+  return {
+    valid: errors.length === 0,
+    errors
+  };
+}
+

package/src/specs/index.mjs

@@ -0,0 +1,38 @@
+/**
+ * Natural Language Specs Sub-Module
+ * 
+ * Natural language specification parsing and execution.
+ * 
+ * Import from 'ai-visual-test/specs'
+ */
+
+// Core spec functions
+export {
+  parseSpec,
+  mapToInterfaces,
+  executeSpec,
+  generatePropertyTests,
+  testBehavior,
+  validateSpec
+} from '../natural-language-specs.mjs';
+
+// Spec templates
+export {
+  TEMPLATES,
+  createSpecFromTemplate,
+  composeTemplates,
+  inheritTemplate,
+  registerTemplate,
+  listTemplates,
+  getTemplate,
+  validateTemplate
+} from '../spec-templates.mjs';
+
+// Spec config
+export {
+  createSpecConfig,
+  getSpecConfig,
+  setSpecConfig,
+  resetSpecConfig
+} from '../spec-config.mjs';
+

package/src/temporal/index.mjs

@@ -0,0 +1,102 @@
+/**
+ * Temporal Sub-Module
+ * 
+ * All temporal aggregation and decision-making functionality.
+ * 
+ * Import from 'ai-visual-test/temporal'
+ */
+
+// Core temporal aggregation
+export {
+  aggregateTemporalNotes,
+  formatNotesForPrompt,
+  calculateCoherenceExported as calculateCoherence
+} from '../temporal.mjs';
+
+// Temporal formatting
+export {
+  formatTemporalContext,
+  formatTemporalForPrompt,
+  formatSingleScaleForPrompt,
+  formatMultiScaleForPrompt
+} from '../temporal-prompt-formatter.mjs';
+
+// Temporal decision management
+export {
+  TemporalDecisionManager,
+  createTemporalDecisionManager
+} from '../temporal-decision-manager.mjs';
+
+// Temporal preprocessing
+export {
+  TemporalPreprocessingManager,
+  AdaptiveTemporalProcessor,
+  createTemporalPreprocessingManager,
+  createAdaptiveTemporalProcessor
+} from '../temporal-preprocessor.mjs';
+
+// Temporal note pruning
+export {
+  pruneTemporalNotes,
+  propagateNotes,
+  selectTopWeightedNotes
+} from '../temporal-note-pruner.mjs';
+
+// Temporal decision functions
+export {
+  aggregateMultiScale,
+  SequentialDecisionContext,
+  humanPerceptionTime,
+  calculateAttentionWeight
+} from '../temporal-decision.mjs';
+
+// Render change detection
+export {
+  detectRenderChanges,
+  calculateOptimalFPS,
+  detectVisualChanges,
+  captureOnRenderChanges,
+  captureAdaptiveTemporalScreenshots
+} from '../render-change-detector.mjs';
+
+// Adaptive temporal
+export {
+  aggregateTemporalNotesAdaptive,
+  calculateOptimalWindowSize,
+  detectActivityPattern
+} from '../temporal-adaptive.mjs';
+
+// Temporal batch optimization
+export { TemporalBatchOptimizer } from '../temporal-batch-optimizer.mjs';
+
+// Temporal context
+export {
+  createTemporalContext,
+  mergeTemporalContext,
+  extractTemporalContext
+} from '../temporal-context.mjs';
+
+// Temporal constants
+export {
+  TIME_SCALES,
+  MULTI_SCALE_WINDOWS,
+  READING_SPEEDS,
+  ATTENTION_MULTIPLIERS,
+  COMPLEXITY_MULTIPLIERS,
+  CONFIDENCE_THRESHOLDS,
+  TIME_BOUNDS,
+  CONTENT_THRESHOLDS
+} from '../temporal-constants.mjs';
+
+// Temporal errors
+export {
+  TemporalError,
+  PerceptionTimeError,
+  SequentialContextError,
+  MultiScaleError,
+  TemporalBatchError
+} from '../temporal-errors.mjs';
+
+// Temporal screenshots (from multi-modal)
+export { captureTemporalScreenshots } from '../multi-modal.mjs';
+

package/src/temporal-adaptive.mjs

@@ -0,0 +1,163 @@
+/**
+ * Adaptive Temporal Aggregation
+ *
+ * Implements adaptive window sizing based on note frequency and activity type.
+ *
+ * Research context:
+ * - "Towards Dynamic Theory of Mind: Evaluating LLM Adaptation to Temporal Evolution of Human States"
+ *   (arXiv:2505.17663) - DynToM benchmark, optimal window sizes vary by activity pattern
+ *   * We use adaptive window sizing based on frequency (loosely related concept)
+ *   * We do NOT implement the DynToM benchmark or its specific methods
+ * - "The Other Mind: How Language Models Exhibit Human Temporal Cognition" (arXiv:2507.15851)
+ *   * Paper discusses Weber-Fechner law: logarithmic compression of temporal perception
+ *   * Paper discusses temporal reference points and hierarchical construction
+ *   * We use LINEAR frequency-based adjustment, NOT logarithmic compression
+ *   * We do NOT implement temporal reference points
+ *
+ * IMPORTANT: This implementation uses LINEAR frequency-based window adjustment, NOT the
+ * logarithmic compression (Weber-Fechner law) described in arXiv:2507.15851. We cite
+ * the papers for adaptive window concepts, but do NOT implement their specific findings.
+ */
+
+import { aggregateTemporalNotes } from './temporal.mjs';
+
+/**
+ * Calculate optimal window size based on note frequency
+ *
+ * @param {import('./index.mjs').TemporalNote[]} notes - Temporal notes
+ * @param {{
+ *   minWindow?: number;
+ *   maxWindow?: number;
+ *   defaultWindow?: number;
+ * }} [options={}] - Options
+ * @returns {number} Optimal window size in milliseconds
+ */
+export function calculateOptimalWindowSize(notes, options = {}) {
+  const {
+    minWindow = 5000,
+    maxWindow = 30000,
+    defaultWindow = 10000
+  } = options;
+
+  if (notes.length < 2) {
+    return defaultWindow;
+  }
+
+  // Calculate note frequency (notes per second)
+  const timeSpan = notes[notes.length - 1].timestamp - notes[0].timestamp;
+  if (timeSpan <= 0) {
+    return defaultWindow;
+  }
+
+  const frequency = notes.length / (timeSpan / 1000); // notes per second
+
+  // Adaptive logic based on frequency
+  // High frequency (>2 notes/sec): use smaller windows
+  // Low frequency (<0.5 notes/sec): use larger windows
+  // Medium frequency: use default window
+
+  if (frequency > 2) {
+    return Math.max(minWindow, defaultWindow * 0.5); // 5s for high frequency
+  } else if (frequency < 0.5) {
+    return Math.min(maxWindow, defaultWindow * 2); // 20s for low frequency
+  } else {
+    return defaultWindow; // 10s for medium frequency
+  }
+}
+
+/**
+ * Detect activity pattern from notes
+ *
+ * @param {import('./index.mjs').TemporalNote[]} notes - Temporal notes
+ * @returns {'fastChange' | 'slowChange' | 'consistent' | 'erratic'} Activity pattern
+ */
+export function detectActivityPattern(notes) {
+  if (notes.length < 3) {
+    return 'consistent';
+  }
+
+  // Calculate change rate
+  const timeSpan = notes[notes.length - 1].timestamp - notes[0].timestamp;
+  const avgTimeBetween = timeSpan / (notes.length - 1);
+
+  // Calculate score variance
+  const scores = notes
+    .map(n => n.gameState?.score || 0)
+    .filter(s => typeof s === 'number');
+
+  if (scores.length < 2) {
+    return 'consistent';
+  }
+
+  const meanScore = scores.reduce((a, b) => a + b, 0) / scores.length;
+  const variance = scores.reduce((sum, score) => sum + Math.pow(score - meanScore, 2), 0) / scores.length;
+
+  // Detect direction changes
+  let directionChanges = 0;
+  for (let i = 1; i < scores.length; i++) {
+    const prev = scores[i - 1];
+    const curr = scores[i];
+    if ((prev < curr && i > 1 && scores[i - 2] > prev) ||
+        (prev > curr && i > 1 && scores[i - 2] < prev)) {
+      directionChanges++;
+    }
+  }
+
+  // Classify pattern
+  if (avgTimeBetween < 1000 && variance > meanScore * 0.5) {
+    return 'fastChange';
+  } else if (avgTimeBetween > 2000 && variance < meanScore * 0.2) {
+    return 'slowChange';
+  } else if (directionChanges > scores.length * 0.3) {
+    return 'erratic';
+  } else {
+    return 'consistent';
+  }
+}
+
+/**
+ * Aggregate temporal notes with adaptive window sizing
+ *
+ * @param {import('./index.mjs').TemporalNote[]} notes - Temporal notes
+ * @param {{
+ *   adaptive?: boolean;
+ *   windowSize?: number;
+ *   decayFactor?: number;
+ *   coherenceThreshold?: number;
+ * }} [options={}] - Aggregation options
+ * @returns {import('./index.mjs').AggregatedTemporalNotes} Aggregated temporal notes
+ */
+export function aggregateTemporalNotesAdaptive(notes, options = {}) {
+  const {
+    adaptive = true,
+    windowSize,
+    decayFactor = 0.9,
+    coherenceThreshold = 0.7
+  } = options;
+
+  let finalWindowSize = windowSize;
+
+  if (adaptive && !windowSize) {
+    // Calculate optimal window size based on note frequency
+    finalWindowSize = calculateOptimalWindowSize(notes);
+
+    // Adjust based on activity pattern
+    const pattern = detectActivityPattern(notes);
+    if (pattern === 'fastChange') {
+      finalWindowSize = Math.min(finalWindowSize, 5000); // Prefer smaller for fast changes
+    } else if (pattern === 'slowChange') {
+      finalWindowSize = Math.max(finalWindowSize, 20000); // Prefer larger for slow changes
+    }
+  } else if (!finalWindowSize) {
+    finalWindowSize = 10000; // Default
+  }
+
+  return aggregateTemporalNotes(notes, {
+    windowSize: finalWindowSize,
+    decayFactor,
+    coherenceThreshold
+  });
+}
+
+
+