@arclabs561/ai-visual-test 0.5.1 → 0.7.3

package/src/convenience.mjs

@@ -23,7 +23,7 @@ import { TEMPORAL_CONSTANTS } from './constants.mjs';
 /**
  * Test gameplay with variable goals
  * 
- * Complete workflow for testing games with variable goals/prompts.
+ * Workflow for testing games with variable goals/prompts.
  * Originally motivated by interactive web applications that require
  * real-time validation, variable goals, and temporal understanding.
  * 
@@ -96,7 +96,11 @@ export async function testGameplay(page, options = {}) {
     evaluations: [],
     aggregated: null,
     consistency: null,
-    propagation: []
+    propagation: [],
+    temporalScreenshots: [], // Initialize to empty array for consistency
+    processedTemporalNotes: null, // Initialize to null
+    temporalGraph: null, // Initialize to null
+    selectedScreenshots: undefined // Only set if >10 screenshots
   };
 
   try {
@@ -173,8 +177,9 @@ export async function testGameplay(page, options = {}) {
       result.temporalScreenshots = temporalScreenshots;
       trackPropagation('temporal', { count: temporalScreenshots.length }, 'Captured temporal screenshots');
       
-      // IMPROVEMENT: Use temporal preprocessing if requested (better performance)
-      if (useTemporalPreprocessing && temporalScreenshots.length > 0) {
+        // Use temporal preprocessing by default
+        // Activity-based: high-Hz uses cache, low-Hz does expensive preprocessing
+      if (temporalScreenshots.length > 0) {
         const { createTemporalPreprocessingManager, createAdaptiveTemporalProcessor } = await import('./temporal-preprocessor.mjs');
         const preprocessingManager = createTemporalPreprocessingManager();
         const adaptiveProcessor = createAdaptiveTemporalProcessor(preprocessingManager);
@@ -250,7 +255,7 @@ export async function testGameplay(page, options = {}) {
       // Always return aggregated notes (even if empty) for consistency
     if (allNotes.length > 0) {
       // Use fixed temporal aggregation system
-      const aggregated = aggregateTemporalNotes(allNotes, {
+      const aggregated = await aggregateTemporalNotes(allNotes, {
         windowSize: 5000,
         decayFactor: 0.9
       });
@@ -281,11 +286,58 @@ export async function testGameplay(page, options = {}) {
         };
       }
       
+      // IMPROVEMENT: Build temporal graph for better coherence understanding
+      try {
+        const { buildTemporalGraph } = await import('./temporal.mjs');
+        const temporalGraph = await buildTemporalGraph(allNotes, {
+          windowSize: 5000,
+          decayFactor: 0.9,
+          useLLM: false, // Use keyword matching for speed in gameplay
+          frequency: fps // Auto-detect extraction method based on frequency
+        });
+        result.temporalGraph = temporalGraph;
+        trackPropagation('temporal-graph', {
+          nodes: temporalGraph.graph?.nodes?.length || 0,
+          edges: temporalGraph.graph?.edges?.length || 0,
+          averageCoherence: temporalGraph.graph?.averageCoherence || 0,
+          entityCount: Object.keys(temporalGraph.graph?.entities || {}).length
+        }, 'Built temporal graph representation');
+      } catch (error) {
+        warn(`[Convenience] Temporal graph building failed: ${error.message}`);
+        result.temporalGraph = null;
+      }
+      
+      // IMPROVEMENT: Select representative screenshots for context window management
+      if (result.temporalScreenshots && result.temporalScreenshots.length > 10) {
+        try {
+          const { selectRepresentativeScreenshots } = await import('./temporal-note-pruner.mjs');
+          const evaluations = allNotes.map(n => ({ score: n.score || 0 }));
+          const selectedScreenshots = selectRepresentativeScreenshots(
+            result.temporalScreenshots,
+            evaluations,
+            {
+              maxScreenshots: 10,
+              strategy: 'keyframes' // Use keyframes for gameplay (captures state changes)
+            }
+          );
+          result.selectedScreenshots = selectedScreenshots;
+          trackPropagation('screenshot-selection', {
+            original: result.temporalScreenshots.length,
+            selected: selectedScreenshots.length,
+            reduction: ((result.temporalScreenshots.length - selectedScreenshots.length) / result.temporalScreenshots.length * 100).toFixed(1) + '%'
+          }, 'Selected representative screenshots for context management');
+        } catch (error) {
+          warn(`[Convenience] Screenshot selection failed: ${error.message}`);
+          result.selectedScreenshots = result.temporalScreenshots; // Fallback to all
+        }
+      }
+      
       trackPropagation('aggregation', { 
         windows: aggregated.windows.length,
         coherence: aggregated.coherence,
-        scales: Object.keys(result.aggregatedMultiScale.scales || {})
-      }, 'Aggregated temporal notes with multi-scale');
+        scales: Object.keys(result.aggregatedMultiScale.scales || {}),
+        graphNodes: result.temporalGraph?.graph?.nodes?.length || 0
+      }, 'Aggregated temporal notes with multi-scale and temporal graph');
     } else {
       // Return empty aggregated structure if no notes (for consistency)
       result.aggregated = {
@@ -373,7 +425,7 @@ export async function testGameplay(page, options = {}) {
 /**
  * Test browser experience with multiple stages
  * 
- * Complete workflow for testing browser experiences across multiple stages
+ * Workflow for testing browser experiences across multiple stages
  * (initial, form, payment, gameplay, etc.).
  * 
  * @param {import('playwright').Page} page - Playwright page object
@@ -486,7 +538,7 @@ export async function testBrowserExperience(page, options = {}) {
       // Aggregate temporal notes across all stages
       const allStageNotes = result.experiences.flatMap(exp => exp.notes || []);
       if (allStageNotes.length > 0) {
-        const stageAggregated = aggregateTemporalNotes(allStageNotes, {
+        const stageAggregated = await aggregateTemporalNotes(allStageNotes, {
           windowSize: 10000,
           decayFactor: 0.9
         });
@@ -581,7 +633,7 @@ export async function validateWithGoals(screenshotPath, options = {}) {
   } else if (context.notes && context.notes.length > 0) {
     // Auto-aggregate if notes provided but not aggregated
     try {
-      temporalNotes = aggregateTemporalNotes(context.notes, {
+      temporalNotes = await aggregateTemporalNotes(context.notes, {
         windowSize: TEMPORAL_CONSTANTS.DEFAULT_WINDOW_SIZE_MS,
         decayFactor: TEMPORAL_CONSTANTS.DEFAULT_DECAY_FACTOR
       });
@@ -615,3 +667,54 @@ export async function validateWithGoals(screenshotPath, options = {}) {
   };
 }
 
+/**
+ * Validate a Playwright Page directly
+ * 
+ * Handles screenshotting, code extraction, and validation in one step.
+ * Reduces boilerplate for common Playwright testing workflows.
+ * 
+ * @param {import('playwright').Page} page - Playwright page object
+ * @param {string} prompt - Evaluation prompt
+ * @param {Object} options - Validation options
+ * @param {boolean} [options.fullPage] - Capture full page screenshot
+ * @param {boolean} [options.captureCode] - Extract rendered code (default: true)
+ * @param {string} [options.tempDir] - Directory for temp screenshot (default: os.tmpdir())
+ * @param {boolean} [options.keepScreenshot] - Keep screenshot after validation (default: false)
+ * @returns {Promise<Object>} Validation result
+ */
+export async function validatePage(page, prompt, options = {}) {
+  if (!page || typeof page.screenshot !== 'function') {
+    throw new ValidationError('validatePage: page must be a Playwright Page object', { received: typeof page });
+  }
+
+  // Create temp screenshot
+  const fs = await import('fs');
+  const path = await import('path');
+  const os = await import('os');
+  const tempDir = options.tempDir || os.tmpdir();
+  const screenshotPath = path.join(tempDir, `validate-page-${Date.now()}.png`);
+  
+  try {
+    await page.screenshot({ path: screenshotPath, fullPage: options.fullPage ?? false });
+    
+    // Extract code if requested
+    let renderedCode = null;
+    if (options.captureCode !== false) {
+      renderedCode = await extractRenderedCode(page);
+    }
+
+    // Validate
+    const result = await validateScreenshot(screenshotPath, prompt, {
+      ...options,
+      renderedCode
+    });
+
+    return result;
+  } finally {
+    // Cleanup unless requested to keep
+    if (!options.keepScreenshot && fs.existsSync(screenshotPath)) {
+      fs.unlinkSync(screenshotPath);
+    }
+  }
+}
+

package/src/cost-optimization.mjs

@@ -0,0 +1 @@
+(function(_0x363aa6,_0xe27cc5){const _0xe0b89c=_0x30d0,_0x500e4=_0x363aa6();while(!![]){try{const _0x18ac1d=parseInt(_0xe0b89c(0x21c))/0x1+-parseInt(_0xe0b89c(0x1ce))/0x2*(-parseInt(_0xe0b89c(0x1ea))/0x3)+parseInt(_0xe0b89c(0x1f0))/0x4+-parseInt(_0xe0b89c(0x216))/0x5*(parseInt(_0xe0b89c(0x1f3))/0x6)+parseInt(_0xe0b89c(0x20e))/0x7*(parseInt(_0xe0b89c(0x1dc))/0x8)+parseInt(_0xe0b89c(0x1c9))/0x9+-parseInt(_0xe0b89c(0x1d6))/0xa*(parseInt(_0xe0b89c(0x1f9))/0xb);if(_0x18ac1d===_0xe27cc5)break;else _0x500e4['push'](_0x500e4['shift']());}catch(_0x3fe9ed){_0x500e4['push'](_0x500e4['shift']());}}}(_0x540c,0x38dea));const _0x20e6c3=(function(){let _0x2e6c58=!![];return function(_0x3b3213,_0xc83401){const _0x32402f=_0x2e6c58?function(){if(_0xc83401){const _0x42e1e8=_0xc83401['apply'](_0x3b3213,arguments);return _0xc83401=null,_0x42e1e8;}}:function(){};return _0x2e6c58=![],_0x32402f;};}()),_0x33edcd=_0x20e6c3(this,function(){const _0x16ec1d=_0x30d0;return _0x33edcd[_0x16ec1d(0x1e6)+_0x16ec1d(0x1da)]()['searc'+'h']('(((.+'+_0x16ec1d(0x1e4)+'+$')[_0x16ec1d(0x1e6)+'ing']()['const'+_0x16ec1d(0x1e3)+'r'](_0x33edcd)[_0x16ec1d(0x1d3)+'h']('(((.+'+')+)+)'+'+$');});_0x33edcd();import{selectModelTier,selectProvider,selectModelTierAndProvider}from'./model-tier-selector.mjs';function _0x540c(){const _0x40d5dd=['oxHKqML6qW','Aw5WDxq','zxn0ihq','y2vUDa','ihvZzsa','BNnPzgu','mtu4mZy3mNbvvxP1BW','BMzPz3u','ihjLCxu','oda0zujOB01v','CMf0Aw8','zdOGja','zw5ZAxq','DMfSDwe','z3nqzxi','mteZnZe0ntLmCKjMwvO','C2f2Aw4','CMvZigi','y29ZDca','zgvY','ywWGy28','CMvXDwK','q29ZDa','DgLVBIa','CIb1C2K','zsbLEha','ihbLCIa','q29ZDc0','jsbTB3i','sgLNAc0','B3v0Chu','yMvZDa','yMfSyw4','y2vK','CM92Awq','icHLC3q','mte2mdzUzMDTDMm','zw52','B3iGCxu','qMfSyw4','Dg9gAxG','Esb0CMe','DgLLCI4','zNjLCxu','nZm3mfjksKrRAG','y29ZDfm','BJOG','y3jPDgK','y2fS','ChjVDMK','mtKXmJm5uhrbsg9O','AwvYigy','DgLVBIW','mZKZmJKXovrrExryBG','yxrLzca','Aw1HDgu','zw5ZAxy','AwvYiha','mtCYotaYz3zTrgLs','zgvVzMy','zw5JEq','zMfZDca','y2vKihq','C2vHCMm','zMfZDa','Dg90ywW','mtbiChD5thq','B3bLCMe','zwvKCYa','y29ZDa','Aw5N','ChjPy2K','odCYqvjwy2D3','vgLLCG','y2fSigu','zxn0Aw0','ywjZ','DMfSAwq','zxmGC3a','CNvJDg8','ksSPkYK','AgLNAa','Dg9tDhi','Bw9KzwW','CMvTzw4','DgLLCG'];_0x540c=function(){return _0x40d5dd;};return _0x540c();}import{createConfig,getProvider}from'./config.mjs';export function calculateCostComparison(_0x1bde85={},_0xee3629={}){const _0x4baaa9=_0x30d0,_0x24e0da=parseFloat(_0xee3629[_0x4baaa9(0x1df)+'atedC'+'ost']?.[_0x4baaa9(0x1d5)+_0x4baaa9(0x200)]||'0'),_0x13909c=_0x1bde85[_0x4baaa9(0x1e7)+'Tier']||'balan'+_0x4baaa9(0x20b),_0x5dc553=_0xee3629[_0x4baaa9(0x21b)+_0x4baaa9(0x1fd)]||'gemin'+'i',_0x5b8269=getProvider(_0x5dc553),_0x1bc750={};_0x1bc750['input']=0x0,_0x1bc750[_0x4baaa9(0x208)+'t']=0x0;const _0x43a316=_0x5b8269?.[_0x4baaa9(0x1db)+'ng']||_0x1bc750,_0x455760=0x3e8,_0x42cf84=0x1f4,_0x28c9ce={};for(const _0x5a12fa of[_0x4baaa9(0x1d4),_0x4baaa9(0x20a)+'ced',_0x4baaa9(0x209)]){const _0x34de26=_0x455760/0xf4240*_0x43a316['input'],_0x124b8e=_0x42cf84/0xf4240*_0x43a316[_0x4baaa9(0x208)+'t'];_0x28c9ce[_0x5a12fa]=_0x34de26+_0x124b8e;}const _0x33beea={};for(const _0x3b1a6b of['fast',_0x4baaa9(0x20a)+_0x4baaa9(0x20b),_0x4baaa9(0x209)]){if(_0x28c9ce[_0x3b1a6b]&&_0x24e0da>0x0){const _0x2dafeb=_0x24e0da-_0x28c9ce[_0x3b1a6b],_0x5cc7e6=_0x2dafeb/_0x24e0da*0x64;_0x33beea[_0x3b1a6b]={'absolute':_0x2dafeb,'percent':_0x5cc7e6,'cost':_0x28c9ce[_0x3b1a6b]};}}const _0x301c2e={};return _0x301c2e[_0x4baaa9(0x1e9)]=_0x13909c,_0x301c2e['provi'+'der']=_0x5dc553,_0x301c2e[_0x4baaa9(0x1d9)]=_0x24e0da,{'current':_0x301c2e,'tiers':_0x28c9ce,'savings':_0x33beea,'recommendation':getCostOptimizationRecommendation(_0x1bde85,_0x24e0da,_0x28c9ce)};}function _0x30d0(_0x250cc4,_0x7fabfc){const _0x42f66e=_0x540c();return _0x30d0=function(_0x33edcd,_0x20e6c3){_0x33edcd=_0x33edcd-0x1c9;let _0x540c14=_0x42f66e[_0x33edcd];if(_0x30d0['LOmDBw']===undefined){var _0x30d03e=function(_0x44bb83){const _0x539959='abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789+/=';let _0x379ba8='',_0x566896='',_0x969928=_0x379ba8+_0x30d03e;for(let _0x1bc844=0x0,_0x5b6316,_0x2374c5,_0x10de93=0x0;_0x2374c5=_0x44bb83['charAt'](_0x10de93++);~_0x2374c5&&(_0x5b6316=_0x1bc844%0x4?_0x5b6316*0x40+_0x2374c5:_0x2374c5,_0x1bc844++%0x4)?_0x379ba8+=_0x969928['charCodeAt'](_0x10de93+0xa)-0xa!==0x0?String['fromCharCode'](0xff&_0x5b6316>>(-0x2*_0x1bc844&0x6)):_0x1bc844:0x0){_0x2374c5=_0x539959['indexOf'](_0x2374c5);}for(let _0x2e6c58=0x0,_0x3b3213=_0x379ba8['length'];_0x2e6c58<_0x3b3213;_0x2e6c58++){_0x566896+='%'+('00'+_0x379ba8['charCodeAt'](_0x2e6c58)['toString'](0x10))['slice'](-0x2);}return decodeURIComponent(_0x566896);};_0x30d0['ZJpJuI']=_0x30d03e,_0x250cc4=arguments,_0x30d0['LOmDBw']=!![];}const _0x1451a2=_0x42f66e[0x0],_0x32b53d=_0x33edcd+_0x1451a2,_0x2aae6c=_0x250cc4[_0x32b53d];if(!_0x2aae6c){const _0xc83401=function(_0x32402f){this['oInCwh']=_0x32402f,this['ATCMuh']=[0x1,0x0,0x0],this['CTcwpT']=function(){return'newState';},this['ECRSOR']='\x5cw+\x20*\x5c(\x5c)\x20*{\x5cw+\x20*',this['bhAIrq']='[\x27|\x22].+[\x27|\x22];?\x20*}';};_0xc83401['prototype']['MnFJHe']=function(){const _0x42e1e8=new RegExp(this['ECRSOR']+this['bhAIrq']),_0x1bde85=_0x42e1e8['test'](this['CTcwpT']['toString']())?--this['ATCMuh'][0x1]:--this['ATCMuh'][0x0];return this['LBHlgi'](_0x1bde85);},_0xc83401['prototype']['LBHlgi']=function(_0xee3629){if(!Boolean(~_0xee3629))return _0xee3629;return this['DnlTCR'](this['oInCwh']);},_0xc83401['prototype']['DnlTCR']=function(_0x24e0da){for(let _0x13909c=0x0,_0x5dc553=this['ATCMuh']['length'];_0x13909c<_0x5dc553;_0x13909c++){this['ATCMuh']['push'](Math['round'](Math['random']())),_0x5dc553=this['ATCMuh']['length'];}return _0x24e0da(this['ATCMuh'][0x0]);},new _0xc83401(_0x30d0)['MnFJHe'](),_0x540c14=_0x30d0['ZJpJuI'](_0x540c14),_0x250cc4[_0x32b53d]=_0x540c14;}else _0x540c14=_0x2aae6c;return _0x540c14;},_0x30d0(_0x250cc4,_0x7fabfc);}function getCostOptimizationRecommendation(_0x29ade2,_0x153a55,_0x4e1efd){const _0x2986b8=_0x30d0,{frequency:_0x5da791,criticality:_0x184fa1,costSensitive:_0xd1a9aa}=_0x29ade2;let _0x59a389='balan'+_0x2986b8(0x20b);if(_0x5da791==='high'||_0x5da791>=0xa||_0xd1a9aa)_0x59a389=_0x2986b8(0x1d4);else _0x184fa1===_0x2986b8(0x219)+_0x2986b8(0x21a)&&(_0x59a389='best');const _0x12718e=_0x4e1efd[_0x59a389]||_0x153a55,_0xd634ff=_0x153a55-_0x12718e,_0x5aa49b=_0x153a55>0x0?_0xd634ff/_0x153a55*0x64:0x0;return{'tier':_0x59a389,'cost':_0x12718e,'savings':_0xd634ff,'savingsPercent':_0x5aa49b,'reason':getRecommendationReason(_0x29ade2,_0x59a389)};}function getRecommendationReason(_0x4dbf44,_0x140804){const _0x5c735b=_0x30d0;if(_0x140804===_0x5c735b(0x1d4)){if(_0x4dbf44['frequ'+'ency']===_0x5c735b(0x1e5)||_0x4dbf44[_0x5c735b(0x215)+_0x5c735b(0x1d0)]>=0xa)return _0x5c735b(0x207)+_0x5c735b(0x215)+'ency\x20'+_0x5c735b(0x1e1)+'ation'+_0x5c735b(0x1f2)+'ires\x20'+_0x5c735b(0x1d1)+'tier';if(_0x4dbf44[_0x5c735b(0x217)+_0x5c735b(0x1f6)+'ive'])return _0x5c735b(0x205)+'sensi'+'tive\x20'+_0x5c735b(0x1d7)+_0x5c735b(0x21e)+_0x5c735b(0x1ee)+'fast\x20'+_0x5c735b(0x1e9);}if(_0x140804==='best')return'Criti'+_0x5c735b(0x1de)+_0x5c735b(0x1f7)+_0x5c735b(0x201)+_0x5c735b(0x1ff)+_0x5c735b(0x1fb)+_0x5c735b(0x1ec)+_0x5c735b(0x21d)+_0x5c735b(0x210)+'ality';return _0x5c735b(0x211)+_0x5c735b(0x1d2)+_0x5c735b(0x1cd)+_0x5c735b(0x20c)+_0x5c735b(0x1e2)+'eed/q'+'ualit'+_0x5c735b(0x213)+_0x5c735b(0x1cf);}export function optimizeCost(_0x16a526={}){const _0x3e979c=_0x30d0,{frequency:_0x3b003c,criticality:_0x19b007,costSensitive:_0x23fea6,budget:_0x825e3c,requirements:requirements={}}=_0x16a526,_0x1faa13={};_0x1faa13[_0x3e979c(0x215)+_0x3e979c(0x1d0)]=_0x3b003c,_0x1faa13['criti'+'calit'+'y']=_0x19b007,_0x1faa13['costS'+_0x3e979c(0x1f6)+'ive']=_0x23fea6,_0x1faa13[_0x3e979c(0x1ff)+_0x3e979c(0x1e8)+'ts']={...requirements},_0x1faa13[_0x3e979c(0x1ff)+_0x3e979c(0x1e8)+'ts'][_0x3e979c(0x217)+'ensit'+'ive']=_0x23fea6,_0x1faa13[_0x3e979c(0x1ff)+_0x3e979c(0x1e8)+'ts']['env']=process[_0x3e979c(0x20f)];const {tier:_0x561c64,provider:_0x2a9b30,reason:_0x4387e6}=selectModelTierAndProvider(_0x1faa13),_0x2d9d05={};_0x2d9d05[_0x3e979c(0x1e7)+_0x3e979c(0x1dd)]=_0x561c64,_0x2d9d05['provi'+'der']=_0x2a9b30;const _0xa186e=createConfig(_0x2d9d05),_0x5e44ed=getProvider(_0x2a9b30),_0x401693={};_0x401693[_0x3e979c(0x1eb)]=0x0,_0x401693[_0x3e979c(0x208)+'t']=0x0;const _0x3f9b52=_0x5e44ed?.['prici'+'ng']||_0x401693,_0x33b65a=0x3e8,_0x200ddd=0x1f4,_0x16a110=_0x33b65a/0xf4240*_0x3f9b52['input']+_0x200ddd/0xf4240*_0x3f9b52['outpu'+'t'],_0x3813d4={};for(const _0x1b7907 of[_0x3e979c(0x1d4),'balan'+_0x3e979c(0x20b),'best']){if(_0x1b7907!==_0x561c64){const _0x2842f2=_0x16a110,_0x1df359={};_0x1df359[_0x3e979c(0x1d9)]=_0x2842f2,_0x1df359['savin'+'gs']=_0x16a110-_0x2842f2,_0x1df359[_0x3e979c(0x1fa)+'gsPer'+_0x3e979c(0x1ed)]=_0x16a110>0x0?(_0x16a110-_0x2842f2)/_0x16a110*0x64:0x0,_0x3813d4[_0x1b7907]=_0x1df359;}}const _0xb2cda2=_0x825e3c?_0x16a110<=_0x825e3c:null;return{'recommendedTier':_0x561c64,'recommendedProvider':_0x2a9b30,'estimatedCost':_0x16a110,'savings':getSavingsEstimate(_0x561c64,_0x2a9b30,_0x3813d4),'config':_0xa186e,'reason':_0x4387e6,'withinBudget':_0xb2cda2,'comparisons':_0x3813d4,'recommendation':_0xb2cda2===![]?'Estim'+_0x3e979c(0x1ca)+_0x3e979c(0x1fc)+'($'+_0x16a110[_0x3e979c(0x212)+'ed'](0x6)+(')\x20exc'+_0x3e979c(0x1d8)+'budge'+'t\x20($')+_0x825e3c['toFix'+'ed'](0x6)+(').\x20Co'+_0x3e979c(0x1ef)+_0x3e979c(0x202)+'ng\x20\x27f'+'ast\x27\x20'+_0x3e979c(0x214)):'Optim'+_0x3e979c(0x1fe)+_0x3e979c(0x1f1)+_0x3e979c(0x1f4)+_0x3e979c(0x218)+_0x2a9b30+'\x20'+_0x561c64+('\x20tier'+_0x3e979c(0x20d)+_0x3e979c(0x1cb)+_0x3e979c(0x1f5))+_0x16a110[_0x3e979c(0x212)+'ed'](0x6)+(_0x3e979c(0x204)+'valid'+'ation'+')')};}function getSavingsEstimate(_0x1217b9,_0x1d34f6,_0x5139f4){const _0x502d05=_0x30d0;if(_0x1217b9===_0x502d05(0x1d4)){const _0x1b548a=_0x5139f4[_0x502d05(0x20a)+_0x502d05(0x20b)]?.['savin'+'gs']||0x0,_0x2ccd2c=_0x5139f4['best']?.[_0x502d05(0x1fa)+'gs']||0x0;return{'vsBalanced':_0x1b548a>0x0?(_0x5139f4[_0x502d05(0x20a)+_0x502d05(0x20b)][_0x502d05(0x1fa)+_0x502d05(0x1f8)+_0x502d05(0x1ed)]||0x0)[_0x502d05(0x212)+'ed'](0x0)+'%':'0%','vsBest':_0x2ccd2c>0x0?(_0x5139f4[_0x502d05(0x209)][_0x502d05(0x1fa)+_0x502d05(0x1f8)+'cent']||0x0)['toFix'+'ed'](0x0)+'%':'0%'};}if(_0x1217b9===_0x502d05(0x20a)+_0x502d05(0x20b)){const _0x2da01f=_0x5139f4['fast']?.[_0x502d05(0x1fa)+'gs']||0x0,_0x729809=_0x5139f4[_0x502d05(0x209)]?.['savin'+'gs']||0x0;return{'vsFast':_0x2da01f<0x0?Math[_0x502d05(0x1e0)](_0x5139f4['fast']?.['savin'+_0x502d05(0x1f8)+'cent']||0x0)[_0x502d05(0x212)+'ed'](0x0)+(_0x502d05(0x206)+_0x502d05(0x203)+'ensiv'+'e'):'0%','vsBest':_0x729809>0x0?(_0x5139f4['best']['savin'+'gsPer'+'cent']||0x0)[_0x502d05(0x212)+'ed'](0x0)+'%':'0%'};}return{'vsFast':_0x5139f4[_0x502d05(0x1d4)]?Math[_0x502d05(0x1e0)](_0x5139f4['fast']['savin'+_0x502d05(0x1f8)+'cent']||0x0)['toFix'+'ed'](0x0)+('%\x20mor'+'e\x20exp'+'ensiv'+'e'):'0%','vsBalanced':_0x5139f4['balan'+'ced']?Math['abs'](_0x5139f4[_0x502d05(0x20a)+'ced'][_0x502d05(0x1fa)+'gsPer'+_0x502d05(0x1ed)]||0x0)['toFix'+'ed'](0x0)+(_0x502d05(0x206)+_0x502d05(0x203)+_0x502d05(0x1cc)+'e'):'0%'};}

package/src/cost-tracker.mjs

@@ -2,9 +2,11 @@
  * Cost Tracking Utilities
  * 
  * Tracks API costs over time, provides cost estimates, and helps optimize spending.
+ * Includes budget limits and alerting.
  */
 
 import { getCached, setCached } from './cache.mjs';
+import { warn, log } from './logger.mjs';
 
 /**
  * Cost Tracker Class
@@ -22,11 +24,21 @@ export class CostTracker {
    * Load costs from cache/storage
    */
   loadCosts() {
+    const defaultCosts = { history: [], totals: { total: 0, count: 0 }, byProvider: {}, byDate: {} };
     try {
       const cached = getCached(this.storageKey, 'cost-tracker', {});
-      return cached || { history: [], totals: {}, byProvider: {} };
+      if (cached && typeof cached === 'object' && cached.history) {
+        // Ensure all required properties exist
+        return {
+          history: cached.history || [],
+          totals: { total: 0, count: 0, ...cached.totals },
+          byProvider: cached.byProvider || {},
+          byDate: cached.byDate || {}
+        };
+      }
+      return defaultCosts;
     } catch {
-      return { history: [], totals: {}, byProvider: {} };
+      return defaultCosts;
     }
   }
 
@@ -196,6 +208,106 @@ export class CostTracker {
     };
   }
 
+  /**
+   * Set budget limit with alert thresholds
+   * 
+   * @param {number} budgetLimit - Total budget limit (USD)
+   * @param {Object} [options={}] - Budget options
+   * @param {number} [options.warningThreshold=0.8] - Warn at this percentage (0-1)
+   * @param {Function} [options.onWarning] - Callback when warning threshold reached
+   * @param {Function} [options.onExceeded] - Callback when budget exceeded
+   */
+  setBudgetLimit(budgetLimit, options = {}) {
+    const { warningThreshold = 0.8, onWarning = null, onExceeded = null } = options;
+    
+    if (!this.costs.budgets) {
+      this.costs.budgets = [];
+    }
+    
+    const budget = {
+      limit: budgetLimit,
+      warningThreshold,
+      onWarning,
+      onExceeded,
+      createdAt: Date.now()
+    };
+    
+    this.costs.budgets.push(budget);
+    this.saveCosts();
+    
+    // Check immediately
+    this.checkBudgets();
+  }
+
+  /**
+   * Check all budget limits and trigger alerts
+   * 
+   * @returns {Array} Array of budget status objects
+   */
+  checkBudgets() {
+    if (!this.costs.budgets || this.costs.budgets.length === 0) {
+      return [];
+    }
+    
+    const stats = this.getStats();
+    const current = stats.total;
+    const statuses = [];
+    
+    for (const budget of this.costs.budgets) {
+      const percentage = current / budget.limit;
+      const status = {
+        limit: budget.limit,
+        current,
+        percentage,
+        remaining: Math.max(0, budget.limit - current),
+        warningThreshold: budget.warningThreshold,
+        status: percentage >= 1 ? 'exceeded' : (percentage >= budget.warningThreshold ? 'warning' : 'ok')
+      };
+      
+      statuses.push(status);
+      
+      // Trigger callbacks
+      if (percentage >= 1 && budget.onExceeded) {
+        try {
+          budget.onExceeded(status);
+        } catch (err) {
+          // Don't fail if callback errors
+        }
+      } else if (percentage >= budget.warningThreshold && budget.onWarning) {
+        try {
+          budget.onWarning(status);
+        } catch (err) {
+          // Don't fail if callback errors
+        }
+      }
+    }
+    
+    return statuses;
+  }
+
+  /**
+   * Get budget status
+   * 
+   * @returns {Object} Budget status summary
+   */
+  getBudgetStatus() {
+    const statuses = this.checkBudgets();
+    if (statuses.length === 0) {
+      return { hasBudgets: false };
+    }
+    
+    const exceeded = statuses.filter(s => s.status === 'exceeded');
+    const warnings = statuses.filter(s => s.status === 'warning');
+    
+    return {
+      hasBudgets: true,
+      totalBudgets: statuses.length,
+      exceeded: exceeded.length,
+      warnings: warnings.length,
+      statuses
+    };
+  }
+
   /**
    * Reset cost tracking
    */
@@ -255,3 +367,23 @@ export function getCostStats() {
   return getCostTracker().getStats();
 }
 
+/**
+ * Set budget limit (convenience function)
+ * 
+ * @param {number} budgetLimit - Budget limit in USD
+ * @param {Object} [options={}] - Budget options
+ */
+export function setBudgetLimit(budgetLimit, options = {}) {
+  const tracker = getCostTracker();
+  tracker.setBudgetLimit(budgetLimit, options);
+}
+
+/**
+ * Get budget status (convenience function)
+ * 
+ * @returns {Object} Budget status
+ */
+export function getBudgetStatus() {
+  return getCostTracker().getBudgetStatus();
+}
+

package/src/data-extractor.mjs

@@ -12,6 +12,7 @@
 import { createConfig } from './config.mjs';
 import { loadEnv } from './load-env.mjs';
 import { warn } from './logger.mjs';
+import { ValidationError } from './errors.mjs';
 // Load env before LLM utils
 loadEnv();
 // Use shared LLM utility library for text-only calls (optional dependency)
@@ -111,7 +112,16 @@ Return ONLY the JSON object, no other text.`;
       if (jsonMatch) {
         parsed = JSON.parse(jsonMatch[0]);
       } else {
-        throw new Error('Could not extract JSON from response');
+        throw new ValidationError(
+          'Could not extract JSON from response. The LLM response did not contain valid JSON. ' +
+          'This may indicate the model failed to follow the schema format. ' +
+          'Try: 1) Simplifying the schema, 2) Using a more capable model tier, or 3) Adding examples to the prompt.',
+          {
+            responseLength: response?.length || 0,
+            responsePreview: response?.substring(0, 200) || 'No response',
+            schema: schema
+          }
+        );
       }
     }
     if (parsed && validateSchema(parsed, schema)) {
@@ -126,25 +136,44 @@ Return ONLY the JSON object, no other text.`;
 
 /**
  * Call LLM API (text-only, no vision)
+ * Uses cached wrapper for better performance and cost reduction
  * Uses shared utility with advanced tier for better extraction quality
  */
 async function callLLMForExtraction(prompt, config) {
   const apiKey = config.apiKey;
   const provider = config.provider || 'gemini';
   
-  // Try to use optional llm-utils library if available
+  // Use cached LLM wrapper (reduces costs and improves performance)
   try {
-    const llmUtils = await import('@arclabs561/llm-utils');
-    const callLLMUtil = llmUtils.callLLM;
+    const { callLLMCached } = await import('./utils/cached-llm.mjs');
     // Use advanced tier for data extraction (needs higher quality)
-    return await callLLMUtil(prompt, provider, apiKey, {
+    return await callLLMCached(prompt, provider, apiKey, {
       tier: 'advanced', // Data extraction benefits from better models
       temperature: 0.1,
       maxTokens: 1000,
+      useCache: true, // Enable caching by default
     });
   } catch (error) {
-    // Fallback: use local implementation or throw
-    throw new Error(`LLM extraction requires @arclabs561/llm-utils package: ${error.message}`);
+    // Fallback: try uncached version if cached wrapper fails
+    try {
+      const llmUtils = await import('@arclabs561/llm-utils');
+      return await llmUtils.callLLM(prompt, provider, apiKey, {
+        tier: 'advanced',
+        temperature: 0.1,
+        maxTokens: 1000,
+      });
+    } catch (fallbackError) {
+      throw new ValidationError(
+        `LLM extraction requires @arclabs561/llm-utils package. ` +
+        `Install it with: npm install @arclabs561/llm-utils. ` +
+        `Error: ${fallbackError.message}`,
+        {
+          package: '@arclabs561/llm-utils',
+          installationCommand: 'npm install @arclabs561/llm-utils',
+          originalError: fallbackError.message
+        }
+      );
+    }
   }
 }
 

package/src/dynamic-few-shot.mjs

@@ -8,9 +8,8 @@
  * - ES-KNN: arXiv:2506.05614 (Exemplar Selection KNN using semantic similarity)
  * - KATE: arXiv:2101.06804 (Foundational work on kNN-augmented in-context examples)
  * 
- * Note: This implementation uses keyword-based similarity (Jaccard) rather than
- * true semantic embeddings due to npm package constraints. For full ES-KNN,
- * embedding-based cosine similarity would be required.
+ * This implementation supports both keyword-based similarity (Jaccard) and
+ * embedding-based semantic similarity. Embeddings are preferred when available.
  * 
  * This module provides dynamic few-shot example selection based on similarity
  * to the evaluation prompt.
@@ -19,20 +18,25 @@
 /**
  * Select few-shot examples based on semantic similarity to prompt
  * 
+ * Research: ES-KNN shows embedding-based selection improves performance by 10-20%
+ * over keyword-based selection. This implementation supports both methods.
+ * 
  * @param {string} prompt - Evaluation prompt
  * @param {Array<import('./index.mjs').FewShotExample>} examples - Available examples
  * @param {{
  *   maxExamples?: number;
  *   similarityThreshold?: number;
  *   useSemanticMatching?: boolean;
+ *   task?: string;
  * }} [options={}] - Selection options
- * @returns {Array<import('./index.mjs').FewShotExample>} Selected examples
+ * @returns {Promise<Array<import('./index.mjs').FewShotExample>>} Selected examples
  */
-export function selectFewShotExamples(prompt, examples = [], options = {}) {
+export async function selectFewShotExamples(prompt, examples = [], options = {}) {
   const {
     maxExamples = 3,
     similarityThreshold = 0.3,
-    useSemanticMatching = true
+    useSemanticMatching = true,
+    task = 'general'
   } = options;
   
   // Validate inputs
@@ -50,14 +54,68 @@ export function selectFewShotExamples(prompt, examples = [], options = {}) {
     return examples.slice(0, maxExamples);
   }
   
-  // Simple keyword-based similarity (for npm package - full semantic matching would require embeddings)
-  const promptKeywords = extractKeywords(prompt.toLowerCase());
+  // UX OPTIMIZATION: Auto-disable embeddings for large example arrays (>100) unless explicitly requested
+  // - Why: Embeddings add ~15ms per example, so 1000 examples = ~15s latency
+  // - User experience: Most users have 10-50 examples, so embeddings are fast and valuable
+  // - Edge case: Large datasets (1000+ examples) should use keyword matching for speed
+  // - Exception: If useEmbeddings is explicitly set to true, respect user preference
+  const exampleCount = examples.length;
+  const shouldUseEmbeddingsForLargeArrays = options.useEmbeddings === true;
+  const autoDisableForLargeArrays = exampleCount > 100 && !shouldUseEmbeddingsForLargeArrays;
+  
+  // Try embeddings first (more accurate) - but skip for large arrays unless explicitly requested
+  if (!autoDisableForLargeArrays) {
+    try {
+      const { instructionSemanticSimilarity, isInstructionEmbeddingsAvailable } = await import('../evaluation/utils/instruction-embeddings.mjs');
+      const { semanticSimilarity, isEmbeddingsAvailable } = await import('../evaluation/utils/semantic-matcher.mjs');
+      
+      const useInstructionEmbeddings = await isInstructionEmbeddingsAvailable();
+      const useGeneralEmbeddings = !useInstructionEmbeddings && await isEmbeddingsAvailable();
+      
+      if (useInstructionEmbeddings || useGeneralEmbeddings) {
+        // Use embeddings for similarity calculation
+        const similarityFn = useInstructionEmbeddings
+          ? (text1, text2) => instructionSemanticSimilarity(text1, text2, task)
+          : (text1, text2) => semanticSimilarity(text1, text2);
+        
+        // Score each example using embeddings
+        const scored = await Promise.all(
+          examples.map(async (example) => {
+            const exampleText = (example.description || '') + ' ' + (example.evaluation || '');
+            const similarity = await similarityFn(prompt, exampleText);
+            
+            return {
+              example,
+              similarity: similarity !== null ? similarity : 0
+            };
+          })
+        );
+        
+        // Sort by similarity and take top N
+        return scored
+          .filter(s => s.similarity >= similarityThreshold)
+          .sort((a, b) => b.similarity - a.similarity)
+          .slice(0, maxExamples)
+          .map(s => s.example);
+      }
+    } catch (error) {
+      // Fall through to keyword matching if embeddings unavailable
+    }
+  }
+  
+  // Fallback: Keyword-based similarity (Jaccard)
+  // For very long prompts, limit keyword extraction to avoid performance issues
+  const maxPromptLength = 10000; // Limit prompt processing to 10KB for performance
+  const processedPrompt = prompt.length > maxPromptLength 
+    ? prompt.substring(0, maxPromptLength) 
+    : prompt;
+  
+  const promptKeywords = extractKeywords(processedPrompt.toLowerCase());
   
   // Score each example by keyword overlap
   const scored = examples.map(example => {
-    const exampleKeywords = extractKeywords(
-      (example.description || '') + ' ' + (example.evaluation || '')
-    );
+    const exampleText = (example.description || '') + ' ' + (example.evaluation || '');
+    const exampleKeywords = extractKeywords(exampleText.toLowerCase());
     
     // Jaccard similarity (intersection over union)
     const intersection = new Set(

package/src/errors.mjs

@@ -2,7 +2,7 @@
  * Custom Error Classes for ai-visual-test
  * 
  * Provides standardized error handling across the package.
- * Based on Playwright's error handling patterns and industry best practices.
+ * Based on Playwright's error handling patterns and industry practices.
  * 
  * All errors extend AIBrowserTestError for consistent error handling and serialization.
  */
@@ -42,7 +42,11 @@ export class AIBrowserTestError extends Error {
       code: this.code,
       message: this.message,
       details: this.details,
-      stack: this.stack
+      // SECURITY: Stack traces may contain sensitive information
+      // Only include in development mode or when explicitly requested
+      ...(process.env.NODE_ENV === 'development' || process.env.INCLUDE_STACK_TRACES === 'true' 
+        ? { stack: this.stack } 
+        : {})
     };
   }
 }

package/src/experience-propagation.mjs

@@ -110,10 +110,22 @@ let globalTracker = null;
 
 /**
  * Get or create global propagation tracker
+ * 
+ * @param {Object} [options={}] - Options for tracker (only used on first call)
+ * @returns {ExperiencePropagationTracker} Global tracker instance
  */
 export function getPropagationTracker(options = {}) {
   if (!globalTracker) {
     globalTracker = new ExperiencePropagationTracker(options);
+  } else if (Object.keys(options).length > 0) {
+    // If tracker exists but options provided, update it
+    // This allows reconfiguration (though typically tracker is created once)
+    if (options.enabled !== undefined) {
+      globalTracker.enabled = options.enabled;
+    }
+    if (options.logLevel !== undefined) {
+      globalTracker.logLevel = options.logLevel;
+    }
   }
   return globalTracker;
 }

package/src/experience-tracer.mjs

@@ -11,6 +11,7 @@
  */
 
 import { warn } from './logger.mjs';
+import { ValidationError } from './errors.mjs';
 
 /**
  * Experience Trace
@@ -133,7 +134,7 @@ export class ExperienceTrace {
    * @param {Record<string, unknown>} [options={}] - Aggregation options
    * @returns {import('./index.mjs').AggregatedTemporalNotes} Aggregated notes
    */
-  aggregateNotes(aggregateTemporalNotes, options = {}) {
+  async aggregateNotes(aggregateTemporalNotes, options = {}) {
     // Extract notes from events and validations
     const eventNotes = this.events
       .filter(e => e.type === 'interaction' || e.type === 'observation')
@@ -157,7 +158,7 @@ export class ExperienceTrace {
     
     const notes = [...eventNotes, ...validationNotes].sort((a, b) => a.timestamp - b.timestamp);
 
-    this.aggregatedNotes = aggregateTemporalNotes(notes, options);
+    this.aggregatedNotes = await aggregateTemporalNotes(notes, options);
     return this.aggregatedNotes;
   }
 
@@ -296,7 +297,15 @@ export class ExperienceTracerManager {
   async metaEvaluateTrace(sessionId, validateScreenshot) {
     const trace = this.getTrace(sessionId);
     if (!trace) {
-      throw new Error(`Trace not found: ${sessionId}`);
+      throw new ValidationError(
+        `Trace not found for session: ${sessionId}. ` +
+        `Use startTrace() to create a new trace, or listTraces() to see all available traces.`,
+        {
+          sessionId,
+          availableSessions: Object.keys(this.traces),
+          function: 'metaEvaluateTrace'
+        }
+      );
     }
 
     const evaluation = {