@arclabs561/ai-visual-test 0.5.1 → 0.7.4

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(_0x18385b,_0x2f2f0a){const _0xa53b50=_0x2d2e,_0x49ca27=_0x18385b();while(!![]){try{const _0xdd5ddf=parseInt(_0xa53b50(0x171))/0x1*(parseInt(_0xa53b50(0x16e))/0x2)+parseInt(_0xa53b50(0x199))/0x3*(-parseInt(_0xa53b50(0x174))/0x4)+parseInt(_0xa53b50(0x19c))/0x5*(parseInt(_0xa53b50(0x180))/0x6)+parseInt(_0xa53b50(0x16b))/0x7*(-parseInt(_0xa53b50(0x195))/0x8)+-parseInt(_0xa53b50(0x17c))/0x9*(-parseInt(_0xa53b50(0x197))/0xa)+-parseInt(_0xa53b50(0x18b))/0xb*(-parseInt(_0xa53b50(0x177))/0xc)+parseInt(_0xa53b50(0x17a))/0xd;if(_0xdd5ddf===_0x2f2f0a)break;else _0x49ca27['push'](_0x49ca27['shift']());}catch(_0x16dc43){_0x49ca27['push'](_0x49ca27['shift']());}}}(_0x1ecb,0x4479d));const _0x40f56c=(function(){let _0x180237=!![];return function(_0x539394,_0xb40faa){const _0x42db3d=_0x180237?function(){if(_0xb40faa){const _0x4b441b=_0xb40faa['apply'](_0x539394,arguments);return _0xb40faa=null,_0x4b441b;}}:function(){};return _0x180237=![],_0x42db3d;};}()),_0xd2e06c=_0x40f56c(this,function(){const _0x212118=_0x2d2e;return _0xd2e06c[_0x212118(0x18c)+'ing']()['searc'+'h'](_0x212118(0x193)+_0x212118(0x188)+'+$')['toStr'+_0x212118(0x198)]()['const'+'ructo'+'r'](_0xd2e06c)[_0x212118(0x167)+'h'](_0x212118(0x193)+_0x212118(0x188)+'+$');});_0xd2e06c();import{selectModelTier,selectProvider,selectModelTierAndProvider}from'./model-tier-selector.mjs';import{createConfig,getProvider}from'./config.mjs';export function calculateCostComparison(_0x57230a={},_0x52fd2f={}){const _0xaa590d=_0x2d2e,_0x33bd6a=parseFloat(_0x52fd2f[_0xaa590d(0x184)+'atedC'+_0xaa590d(0x168)]?.['total'+'Cost']||'0'),_0x397464=_0x57230a['model'+_0xaa590d(0x1a7)]||'balan'+_0xaa590d(0x173),_0x238e4b=_0x52fd2f['provi'+'der']||'gemin'+'i',_0x5ef67d=getProvider(_0x238e4b),_0x48530e={};_0x48530e['input']=0x0,_0x48530e['outpu'+'t']=0x0;const _0x26c913=_0x5ef67d?.[_0xaa590d(0x181)+'ng']||_0x48530e,_0x4f9c20=0x3e8,_0x321d8d=0x1f4,_0x578480={};for(const _0x1ff61d of[_0xaa590d(0x182),_0xaa590d(0x19b)+'ced','best']){const _0x161f86=_0x4f9c20/0xf4240*_0x26c913['input'],_0x519e8b=_0x321d8d/0xf4240*_0x26c913[_0xaa590d(0x1a1)+'t'];_0x578480[_0x1ff61d]=_0x161f86+_0x519e8b;}const _0x420aba={};for(const _0xf4fc80 of[_0xaa590d(0x182),'balan'+_0xaa590d(0x173),_0xaa590d(0x1a9)]){if(_0x578480[_0xf4fc80]&&_0x33bd6a>0x0){const _0x1573e6=_0x33bd6a-_0x578480[_0xf4fc80],_0x36dd72=_0x1573e6/_0x33bd6a*0x64;_0x420aba[_0xf4fc80]={'absolute':_0x1573e6,'percent':_0x36dd72,'cost':_0x578480[_0xf4fc80]};}}const _0x31be62={};return _0x31be62['tier']=_0x397464,_0x31be62[_0xaa590d(0x169)+'der']=_0x238e4b,_0x31be62[_0xaa590d(0x1a4)]=_0x33bd6a,{'current':_0x31be62,'tiers':_0x578480,'savings':_0x420aba,'recommendation':getCostOptimizationRecommendation(_0x57230a,_0x33bd6a,_0x578480)};}function getCostOptimizationRecommendation(_0x48b039,_0x19d13e,_0x2fc7c2){const _0x509a09=_0x2d2e,{frequency:_0x3a7aef,criticality:_0x1ccde8,costSensitive:_0x4f54d4}=_0x48b039;let _0x2bcee6=_0x509a09(0x19b)+_0x509a09(0x173);if(_0x3a7aef===_0x509a09(0x18e)||_0x3a7aef>=0xa||_0x4f54d4)_0x2bcee6=_0x509a09(0x182);else _0x1ccde8===_0x509a09(0x18f)+_0x509a09(0x194)&&(_0x2bcee6='best');const _0x505d15=_0x2fc7c2[_0x2bcee6]||_0x19d13e,_0x44afb3=_0x19d13e-_0x505d15,_0x10c8ba=_0x19d13e>0x0?_0x44afb3/_0x19d13e*0x64:0x0;return{'tier':_0x2bcee6,'cost':_0x505d15,'savings':_0x44afb3,'savingsPercent':_0x10c8ba,'reason':getRecommendationReason(_0x48b039,_0x2bcee6)};}function getRecommendationReason(_0x598c0e,_0xf227a9){const _0x30edec=_0x2d2e;if(_0xf227a9==='fast'){if(_0x598c0e[_0x30edec(0x185)+'ency']===_0x30edec(0x18e)||_0x598c0e['frequ'+_0x30edec(0x1a2)]>=0xa)return _0x30edec(0x1a5)+_0x30edec(0x185)+'ency\x20'+_0x30edec(0x17d)+_0x30edec(0x187)+'\x20requ'+_0x30edec(0x196)+_0x30edec(0x179)+_0x30edec(0x192);if(_0x598c0e[_0x30edec(0x189)+'ensit'+'ive'])return _0x30edec(0x1ac)+'sensi'+'tive\x20'+_0x30edec(0x183)+_0x30edec(0x1ab)+'\x20use\x20'+_0x30edec(0x179)+_0x30edec(0x192);}if(_0xf227a9==='best')return'Criti'+_0x30edec(0x178)+'valua'+_0x30edec(0x190)+_0x30edec(0x16f)+'res\x20b'+'est\x20t'+_0x30edec(0x1a3)+'or\x20qu'+_0x30edec(0x1aa);return'Balan'+_0x30edec(0x18a)+_0x30edec(0x170)+'rovid'+'es\x20sp'+'eed/q'+_0x30edec(0x1a6)+'y\x20tra'+'deoff';}function _0x2d2e(_0x2bf370,_0x100b7e){const _0x3462a3=_0x1ecb();return _0x2d2e=function(_0xd2e06c,_0x40f56c){_0xd2e06c=_0xd2e06c-0x167;let _0x1ecb23=_0x3462a3[_0xd2e06c];if(_0x2d2e['clmymu']===undefined){var _0x2d2e4c=function(_0x4d9406){const _0x4347ab='abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789+/=';let _0x91f6aa='',_0x4491a1='',_0x428b38=_0x91f6aa+_0x2d2e4c;for(let _0x2de447=0x0,_0x464545,_0x5ec257,_0x372eca=0x0;_0x5ec257=_0x4d9406['charAt'](_0x372eca++);~_0x5ec257&&(_0x464545=_0x2de447%0x4?_0x464545*0x40+_0x5ec257:_0x5ec257,_0x2de447++%0x4)?_0x91f6aa+=_0x428b38['charCodeAt'](_0x372eca+0xa)-0xa!==0x0?String['fromCharCode'](0xff&_0x464545>>(-0x2*_0x2de447&0x6)):_0x2de447:0x0){_0x5ec257=_0x4347ab['indexOf'](_0x5ec257);}for(let _0x180237=0x0,_0x539394=_0x91f6aa['length'];_0x180237<_0x539394;_0x180237++){_0x4491a1+='%'+('00'+_0x91f6aa['charCodeAt'](_0x180237)['toString'](0x10))['slice'](-0x2);}return decodeURIComponent(_0x4491a1);};_0x2d2e['YBBLwq']=_0x2d2e4c,_0x2bf370=arguments,_0x2d2e['clmymu']=!![];}const _0x5bd10d=_0x3462a3[0x0],_0x25f117=_0xd2e06c+_0x5bd10d,_0x4bfa19=_0x2bf370[_0x25f117];if(!_0x4bfa19){const _0xb40faa=function(_0x42db3d){this['tUiOdk']=_0x42db3d,this['yllaQc']=[0x1,0x0,0x0],this['eWSZJt']=function(){return'newState';},this['NeSNJo']='\x5cw+\x20*\x5c(\x5c)\x20*{\x5cw+\x20*',this['jVFOWK']='[\x27|\x22].+[\x27|\x22];?\x20*}';};_0xb40faa['prototype']['JTaKsI']=function(){const _0x4b441b=new RegExp(this['NeSNJo']+this['jVFOWK']),_0x57230a=_0x4b441b['test'](this['eWSZJt']['toString']())?--this['yllaQc'][0x1]:--this['yllaQc'][0x0];return this['eHArMZ'](_0x57230a);},_0xb40faa['prototype']['eHArMZ']=function(_0x52fd2f){if(!Boolean(~_0x52fd2f))return _0x52fd2f;return this['AIYzCx'](this['tUiOdk']);},_0xb40faa['prototype']['AIYzCx']=function(_0x33bd6a){for(let _0x397464=0x0,_0x238e4b=this['yllaQc']['length'];_0x397464<_0x238e4b;_0x397464++){this['yllaQc']['push'](Math['round'](Math['random']())),_0x238e4b=this['yllaQc']['length'];}return _0x33bd6a(this['yllaQc'][0x0]);},new _0xb40faa(_0x2d2e)['JTaKsI'](),_0x1ecb23=_0x2d2e['YBBLwq'](_0x1ecb23),_0x2bf370[_0x25f117]=_0x1ecb23;}else _0x1ecb23=_0x4bfa19;return _0x1ecb23;},_0x2d2e(_0x2bf370,_0x100b7e);}export function optimizeCost(_0x157b14={}){const _0x46d2fd=_0x2d2e,{frequency:_0x11c64d,criticality:_0x1162ee,costSensitive:_0x2e4e15,budget:_0x2fbb39,requirements:requirements={}}=_0x157b14,_0x5d2c5d={};_0x5d2c5d[_0x46d2fd(0x185)+'ency']=_0x11c64d,_0x5d2c5d[_0x46d2fd(0x18f)+_0x46d2fd(0x1a0)+'y']=_0x1162ee,_0x5d2c5d['costS'+'ensit'+'ive']=_0x2e4e15,_0x5d2c5d[_0x46d2fd(0x16f)+_0x46d2fd(0x186)+'ts']={...requirements},_0x5d2c5d[_0x46d2fd(0x16f)+_0x46d2fd(0x186)+'ts'][_0x46d2fd(0x189)+'ensit'+'ive']=_0x2e4e15,_0x5d2c5d[_0x46d2fd(0x16f)+_0x46d2fd(0x186)+'ts']['env']=process[_0x46d2fd(0x17f)];const {tier:_0x214f9b,provider:_0x20c49a,reason:_0x5c1bce}=selectModelTierAndProvider(_0x5d2c5d),_0xdaa5b8={};_0xdaa5b8['model'+'Tier']=_0x214f9b,_0xdaa5b8[_0x46d2fd(0x169)+_0x46d2fd(0x19a)]=_0x20c49a;const _0xfb6ace=createConfig(_0xdaa5b8),_0x56ddaf=getProvider(_0x20c49a),_0x409eff={};_0x409eff['input']=0x0,_0x409eff['outpu'+'t']=0x0;const _0x422e41=_0x56ddaf?.[_0x46d2fd(0x181)+'ng']||_0x409eff,_0x117a81=0x3e8,_0x510ec9=0x1f4,_0x59906d=_0x117a81/0xf4240*_0x422e41[_0x46d2fd(0x16c)]+_0x510ec9/0xf4240*_0x422e41[_0x46d2fd(0x1a1)+'t'],_0x39264a={};for(const _0x149af7 of['fast',_0x46d2fd(0x19b)+'ced','best']){if(_0x149af7!==_0x214f9b){const _0x87f361=_0x59906d,_0x3fad65={};_0x3fad65['cost']=_0x87f361,_0x3fad65[_0x46d2fd(0x19e)+'gs']=_0x59906d-_0x87f361,_0x3fad65[_0x46d2fd(0x19e)+'gsPer'+_0x46d2fd(0x19f)]=_0x59906d>0x0?(_0x59906d-_0x87f361)/_0x59906d*0x64:0x0,_0x39264a[_0x149af7]=_0x3fad65;}}const _0x449d7a=_0x2fbb39?_0x59906d<=_0x2fbb39:null;return{'recommendedTier':_0x214f9b,'recommendedProvider':_0x20c49a,'estimatedCost':_0x59906d,'savings':getSavingsEstimate(_0x214f9b,_0x20c49a,_0x39264a),'config':_0xfb6ace,'reason':_0x5c1bce,'withinBudget':_0x449d7a,'comparisons':_0x39264a,'recommendation':_0x449d7a===![]?_0x46d2fd(0x191)+'ated\x20'+'cost\x20'+'($'+_0x59906d[_0x46d2fd(0x1ad)+'ed'](0x6)+(')\x20exc'+_0x46d2fd(0x175)+'budge'+'t\x20($')+_0x2fbb39[_0x46d2fd(0x1ad)+'ed'](0x6)+(_0x46d2fd(0x17b)+_0x46d2fd(0x172)+'r\x20usi'+'ng\x20\x27f'+_0x46d2fd(0x16d)+'tier.'):'Optim'+'al\x20co'+_0x46d2fd(0x18d)+'ratio'+'n:\x20'+_0x20c49a+'\x20'+_0x214f9b+(_0x46d2fd(0x19d)+'\x20(est'+'imate'+_0x46d2fd(0x1ae))+_0x59906d[_0x46d2fd(0x1ad)+'ed'](0x6)+('\x20per\x20'+'valid'+_0x46d2fd(0x187)+')')};}function getSavingsEstimate(_0x1521bc,_0x3e64cf,_0x151d7f){const _0x373a2c=_0x2d2e;if(_0x1521bc===_0x373a2c(0x182)){const _0x36077e=_0x151d7f['balan'+_0x373a2c(0x173)]?.['savin'+'gs']||0x0,_0xbf31ee=_0x151d7f['best']?.[_0x373a2c(0x19e)+'gs']||0x0;return{'vsBalanced':_0x36077e>0x0?(_0x151d7f[_0x373a2c(0x19b)+_0x373a2c(0x173)]['savin'+_0x373a2c(0x16a)+_0x373a2c(0x19f)]||0x0)['toFix'+'ed'](0x0)+'%':'0%','vsBest':_0xbf31ee>0x0?(_0x151d7f[_0x373a2c(0x1a9)][_0x373a2c(0x19e)+_0x373a2c(0x16a)+_0x373a2c(0x19f)]||0x0)[_0x373a2c(0x1ad)+'ed'](0x0)+'%':'0%'};}if(_0x1521bc===_0x373a2c(0x19b)+'ced'){const _0xa4c8f8=_0x151d7f['fast']?.['savin'+'gs']||0x0,_0x23d59f=_0x151d7f['best']?.[_0x373a2c(0x19e)+'gs']||0x0;return{'vsFast':_0xa4c8f8<0x0?Math[_0x373a2c(0x1a8)](_0x151d7f[_0x373a2c(0x182)]?.['savin'+_0x373a2c(0x16a)+_0x373a2c(0x19f)]||0x0)['toFix'+'ed'](0x0)+(_0x373a2c(0x17e)+'e\x20exp'+_0x373a2c(0x176)+'e'):'0%','vsBest':_0x23d59f>0x0?(_0x151d7f['best'][_0x373a2c(0x19e)+'gsPer'+'cent']||0x0)[_0x373a2c(0x1ad)+'ed'](0x0)+'%':'0%'};}return{'vsFast':_0x151d7f[_0x373a2c(0x182)]?Math['abs'](_0x151d7f[_0x373a2c(0x182)]['savin'+_0x373a2c(0x16a)+'cent']||0x0)['toFix'+'ed'](0x0)+(_0x373a2c(0x17e)+'e\x20exp'+'ensiv'+'e'):'0%','vsBalanced':_0x151d7f[_0x373a2c(0x19b)+'ced']?Math['abs'](_0x151d7f[_0x373a2c(0x19b)+'ced'][_0x373a2c(0x19e)+_0x373a2c(0x16a)+'cent']||0x0)['toFix'+'ed'](0x0)+('%\x20mor'+'e\x20exp'+'ensiv'+'e'):'0%'};}function _0x1ecb(){const _0xa9d53f=['B3v0Chu','zw5JEq','AwvYigy','y29ZDa','sgLNAc0','DwfSAxq','vgLLCG','ywjZ','yMvZDa','ywXPDhK','DgLVBIW','q29ZDc0','Dg9gAxG','zdOGja','C2vHCMm','B3n0','ChjVDMK','z3nqzxi','mti2zgnotfDj','Aw5WDxq','yxn0jYa','nJyYogXUA1nRBq','CMvXDwK','AwvYiha','mtjgCNb5Cxe','BNnPzgu','y2vK','mtaYmtzJB3bkChu','zwvKCYa','zw5ZAxy','mtq2nZzxvgnduMO','y2fSigu','zMfZDca','ntKWmZnwsxPhruO','ks4Gq28','ndqWnZnkBhHUsK0','DMfSAwq','jsbTB3i','zw52','mZC5ogrsuuvgza','ChjPy2K','zMfZDa','B3bLCMe','zxn0Aw0','zNjLCxu','CMvTzw4','yxrPB24','ksSPkYK','y29ZDfm','y2vKihq','ndK5nezSrvjpDW','Dg9tDhi','BMzPz3u','AgLNAa','y3jPDgK','DgLVBIa','rxn0Aw0','DgLLCG','kcGOlIS','y2fS','mJiYntq0r0vtywDL','AxjLCYa','odKWCfPWyNfX','Aw5N','mZKZBhLSD3jo','zgvY','yMfSyw4','nJm1qwHeEeTT','ihrPzxi','C2f2Aw4','y2vUDa','y2fSAxq'];_0x1ecb=function(){return _0xa9d53f;};return _0x1ecb();}

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 = {