web-agent-bridge 2.7.0 → 2.8.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-agent-bridge",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "Open-source middleware that bridges AI agents and websites — providing a standardized command interface for intelligent automation",
   "main": "server/index.js",
   "bin": {

package/sdk/package.json

@@ -1,6 +1,6 @@
 {
   "name": "web-agent-bridge-sdk",
-  "version": "2.7.0",
+  "version": "2.8.0",
   "description": "SDK for building AI agents that interact with Web Agent Bridge (WAB)",
   "main": "index.js",
   "license": "MIT",

package/server/routes/runtime.js

@@ -34,6 +34,8 @@ const metering = require('../services/metering');
 const { marketplace } = require('../services/marketplace');
 const { hostedRuntime } = require('../services/hosted-runtime');
 const { sessionEngine } = require('../runtime/session-engine');
+const vision = require('../services/vision');
+const { lfdEngine } = require('../services/lfd');
 
 // ═══════════════════════════════════════════════════════════════════════════
 // AUTH MIDDLEWARE
@@ -55,6 +57,12 @@ const PUBLIC_PATHS = [
   '/registry/templates',
   '/plans',
   '/marketplace',
+  '/recipes',
+  '/vision/models',
+  '/vision/extraction-script',
+  '/recipes',
+  '/vision/models',
+  '/vision/extraction-script',
 ];
 
 function authMiddleware(req, res, next) {
@@ -534,6 +542,7 @@ router.get('/observability/health', (req, res) => {
   health.marketplace = marketplace.getStats();
   health.hostedRuntime = hostedRuntime.getStats();
   health.metering = metering.getStats();
+  health.lfd = lfdEngine.getStats();
   res.json(health);
 });
 
@@ -1443,4 +1452,298 @@ router.get('/hosted/stats', (req, res) => {
   res.json(hostedRuntime.getStats());
 });
 
+// ═══════════════════════════════════════════════════════════════════════════
+// LOCAL VISION ENGINE (Self-contained — no external API)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Analyze page DOM locally (no external API calls)
+ */
+router.post('/vision/analyze-dom', async (req, res) => {
+  try {
+    const siteId = req.body.siteId || req.agentId || 'default';
+    const result = await vision.analyzePageDOM(siteId, {
+      domSnapshot: req.body.domSnapshot,
+      url: req.body.url,
+    });
+    res.json(result);
+  } catch (err) {
+    res.status(400).json({ error: err.message });
+  }
+});
+
+/**
+ * Get DOM extraction script to inject into pages
+ */
+router.get('/vision/extraction-script', (req, res) => {
+  res.json({ script: vision.getDomExtractionScript() });
+});
+
+/**
+ * Find elements in cached vision data
+ */
+router.get('/vision/elements', (req, res) => {
+  const siteId = req.query.siteId || req.agentId || 'default';
+  const results = vision.findElement(siteId, req.query.url, {
+    description: req.query.q,
+    type: req.query.type,
+    label: req.query.label,
+  });
+  res.json({ elements: results, total: results.length });
+});
+
+/**
+ * Vision history
+ */
+router.get('/vision/history', (req, res) => {
+  const siteId = req.query.siteId || req.agentId || 'default';
+  const history = vision.getVisionHistory(siteId, {
+    limit: parseInt(req.query.limit) || 50,
+    url: req.query.url,
+  });
+  res.json({ history, total: history.length });
+});
+
+/**
+ * Supported vision models
+ */
+router.get('/vision/models', (req, res) => {
+  res.json({ models: vision.getSupportedModels() });
+});
+
+// ═══════════════════════════════════════════════════════════════════════════
+// LEARNING FROM DEMONSTRATION (LfD)
+// ═══════════════════════════════════════════════════════════════════════════
+
+/**
+ * Start a recording session
+ */
+router.post('/lfd/record', (req, res) => {
+  try {
+    const session = lfdEngine.startRecording({
+      name: req.body.name,
+      description: req.body.description,
+      agentId: req.agentId || req.body.agentId,
+      startUrl: req.body.startUrl,
+      tags: req.body.tags,
+    });
+    res.json(session);
+  } catch (err) {
+    res.status(400).json({ error: err.message });
+  }
+});
+
+/**
+ * Record events into a session
+ */
+router.post('/lfd/:sessionId/events', (req, res) => {
+  try {
+    const events = req.body.events || [req.body];
+    const results = events.map(evt => lfdEngine.recordEvent(req.params.sessionId, evt));
+    res.json({ recorded: results.filter(Boolean).length });
+  } catch (err) {
+    res.status(400).json({ error: err.message });
+  }
+});
+
+/**
+ * Record a DOM snapshot
+ */
+router.post('/lfd/:sessionId/snapshot', (req, res) => {
+  try {
+    lfdEngine.recordSnapshot(req.params.sessionId, req.body);
+    res.json({ success: true });
+  } catch (err) {
+    res.status(400).json({ error: err.message });
+  }
+});
+
+/**
+ * Pause recording
+ */
+router.post('/lfd/:sessionId/pause', (req, res) => {
+  try { res.json(lfdEngine.pauseRecording(req.params.sessionId)); }
+  catch (err) { res.status(400).json({ error: err.message }); }
+});
+
+/**
+ * Resume recording
+ */
+router.post('/lfd/:sessionId/resume', (req, res) => {
+  try { res.json(lfdEngine.resumeRecording(req.params.sessionId)); }
+  catch (err) { res.status(400).json({ error: err.message }); }
+});
+
+/**
+ * Stop recording and generate recipe
+ */
+router.post('/lfd/:sessionId/stop', (req, res) => {
+  try { res.json(lfdEngine.stopRecording(req.params.sessionId)); }
+  catch (err) { res.status(400).json({ error: err.message }); }
+});
+
+/**
+ * Cancel recording
+ */
+router.post('/lfd/:sessionId/cancel', (req, res) => {
+  try { res.json(lfdEngine.cancelRecording(req.params.sessionId)); }
+  catch (err) { res.status(400).json({ error: err.message }); }
+});
+
+/**
+ * Get recording details
+ */
+router.get('/lfd/:sessionId', (req, res) => {
+  const recording = lfdEngine.getRecording(req.params.sessionId);
+  if (!recording) return res.status(404).json({ error: 'Recording not found' });
+  res.json(recording);
+});
+
+/**
+ * List recordings
+ */
+router.get('/lfd', (req, res) => {
+  res.json({ recordings: lfdEngine.listRecordings(parseInt(req.query.limit) || 50) });
+});
+
+/**
+ * Get recording script to inject into pages
+ */
+router.get('/lfd/:sessionId/script', (req, res) => {
+  const serverUrl = `${req.protocol}://${req.get('host')}`;
+  res.json({ script: lfdEngine.getRecordingScript(req.params.sessionId, serverUrl) });
+});
+
+// ── Recipes ──
+
+/**
+ * List recipes
+ */
+router.get('/recipes', (req, res) => {
+  const recipes = lfdEngine.listRecipes({
+    domain: req.query.domain,
+    tag: req.query.tag,
+    query: req.query.q,
+  }, parseInt(req.query.limit) || 50);
+  res.json({ recipes, total: recipes.length });
+});
+
+/**
+ * Get recipe
+ */
+router.get('/recipes/:recipeId', (req, res) => {
+  const recipe = lfdEngine.getRecipe(req.params.recipeId);
+  if (!recipe) return res.status(404).json({ error: 'Recipe not found' });
+  res.json(recipe);
+});
+
+/**
+ * Save/import recipe manually
+ */
+router.post('/recipes', (req, res) => {
+  try { res.json(lfdEngine.saveRecipe(req.body)); }
+  catch (err) { res.status(400).json({ error: err.message }); }
+});
+
+/**
+ * Delete recipe
+ */
+router.delete('/recipes/:recipeId', (req, res) => {
+  const deleted = lfdEngine.deleteRecipe(req.params.recipeId);
+  res.json({ deleted });
+});
+
+/**
+ * Execute a recipe
+ */
+router.post('/recipes/:recipeId/execute', (req, res) => {
+  try {
+    const execution = lfdEngine.executeRecipe(req.params.recipeId, {
+      variables: req.body.variables,
+      speed: req.body.speed,
+      stopOnError: req.body.stopOnError,
+      skipWaits: req.body.skipWaits,
+      humanInTheLoop: req.body.humanInTheLoop,
+    });
+    res.json(execution);
+  } catch (err) {
+    res.status(400).json({ error: err.message });
+  }
+});
+
+/**
+ * Get next step in execution
+ */
+router.get('/executions/:executionId/next', (req, res) => {
+  const step = lfdEngine.getNextStep(req.params.executionId);
+  if (!step) {
+    const exec = lfdEngine.getExecution(req.params.executionId);
+    return res.json({ done: true, status: exec?.status || 'unknown' });
+  }
+  res.json(step);
+});
+
+/**
+ * Report step result
+ */
+router.post('/executions/:executionId/steps/:stepIndex', (req, res) => {
+  const exec = lfdEngine.reportStep(
+    req.params.executionId,
+    parseInt(req.params.stepIndex),
+    { success: req.body.success, error: req.body.error, duration: req.body.duration, selectorUsed: req.body.selectorUsed }
+  );
+  if (!exec) return res.status(404).json({ error: 'Execution not found' });
+  res.json({ status: exec.status, currentStep: exec.currentStep, totalSteps: exec.totalSteps });
+});
+
+/**
+ * Pause execution
+ */
+router.post('/executions/:executionId/pause', (req, res) => {
+  const exec = lfdEngine.pauseExecution(req.params.executionId);
+  if (!exec) return res.status(404).json({ error: 'Execution not found' });
+  res.json({ status: exec.status });
+});
+
+/**
+ * Resume execution
+ */
+router.post('/executions/:executionId/resume', (req, res) => {
+  const exec = lfdEngine.resumeExecution(req.params.executionId);
+  if (!exec) return res.status(404).json({ error: 'Execution not found' });
+  res.json({ status: exec.status });
+});
+
+/**
+ * Abort execution
+ */
+router.post('/executions/:executionId/abort', (req, res) => {
+  const exec = lfdEngine.abortExecution(req.params.executionId);
+  if (!exec) return res.status(404).json({ error: 'Execution not found' });
+  res.json({ status: exec.status });
+});
+
+/**
+ * Get execution details
+ */
+router.get('/executions/:executionId', (req, res) => {
+  const exec = lfdEngine.getExecution(req.params.executionId);
+  if (!exec) return res.status(404).json({ error: 'Execution not found' });
+  res.json(exec);
+});
+
+/**
+ * List executions
+ */
+router.get('/executions', (req, res) => {
+  res.json({ executions: lfdEngine.listExecutions(parseInt(req.query.limit) || 50) });
+});
+
+/**
+ * LfD stats
+ */
+router.get('/lfd/stats', (req, res) => {
+  res.json(lfdEngine.getStats());
+});
+
 module.exports = router;

package/server/services/lfd.js

@@ -0,0 +1,616 @@
+'use strict';
+
+/**
+ * Learning from Demonstration (LfD) Engine
+ *
+ * Records user actions on web pages, converts them to replayable recipes,
+ * and enables agents to learn from human demonstrations.
+ *
+ * Flow:
+ * 1. User starts a recording session
+ * 2. Browser captures events (clicks, typing, navigation, scrolls)
+ * 3. Each event includes DOM snapshot + screenshot hash + element info
+ * 4. Session is saved as a "Recipe" (YAML/JSON task template)
+ * 5. Recipes can be replayed by agents on the same or similar sites
+ * 6. Recipes can be shared via the Marketplace
+ */
+
+const crypto = require('crypto');
+
+// ═══════════════════════════════════════════════════════════════════
+// RECORDING SESSION
+// ═══════════════════════════════════════════════════════════════════
+
+class RecordingSession {
+  constructor(config = {}) {
+    this.id = crypto.randomUUID();
+    this.name = config.name || 'Untitled Recording';
+    this.description = config.description || '';
+    this.agentId = config.agentId || null;
+    this.startUrl = config.startUrl || '';
+    this.status = 'recording'; // recording | paused | completed | cancelled
+    this.events = [];
+    this.snapshots = []; // DOM snapshots at key moments
+    this.metadata = {
+      startedAt: Date.now(),
+      completedAt: null,
+      duration: 0,
+      pageCount: 0,
+      actionCount: 0,
+      domain: '',
+      tags: config.tags || [],
+    };
+    try { this.metadata.domain = new URL(config.startUrl).hostname; } catch {}
+  }
+
+  /**
+   * Record a user action event
+   */
+  addEvent(event) {
+    if (this.status !== 'recording') return null;
+
+    const recorded = {
+      id: `evt-${this.events.length}`,
+      seq: this.events.length,
+      timestamp: Date.now(),
+      relativeTime: Date.now() - this.metadata.startedAt,
+      type: event.type, // click | type | navigate | scroll | select | hover | wait | assert
+      target: {
+        selector: event.selector || '',
+        xpath: event.xpath || '',
+        text: (event.text || '').slice(0, 200),
+        tag: event.tag || '',
+        attributes: event.attributes || {},
+        rect: event.rect || {},
+      },
+      data: {}, // type-specific data
+      url: event.url || '',
+      pageTitle: event.pageTitle || '',
+      screenshot: event.screenshotHash || null,
+    };
+
+    // Type-specific data
+    switch (event.type) {
+      case 'click':
+        recorded.data = { x: event.x, y: event.y, button: event.button || 'left', doubleClick: !!event.doubleClick };
+        break;
+      case 'type':
+        recorded.data = { value: event.value || '', key: event.key || '', clearFirst: !!event.clearFirst };
+        break;
+      case 'navigate':
+        recorded.data = { url: event.url || '', method: event.method || 'goto' };
+        this.metadata.pageCount++;
+        break;
+      case 'scroll':
+        recorded.data = { x: event.scrollX || 0, y: event.scrollY || 0, direction: event.direction || 'down' };
+        break;
+      case 'select':
+        recorded.data = { value: event.value || '', label: event.label || '', index: event.index };
+        break;
+      case 'hover':
+        recorded.data = { duration: event.duration || 0 };
+        break;
+      case 'wait':
+        recorded.data = { ms: event.ms || 1000, condition: event.condition || 'delay' };
+        break;
+      case 'assert':
+        recorded.data = { assertion: event.assertion || '', expected: event.expected };
+        break;
+      case 'keypress':
+        recorded.data = { key: event.key || '', modifiers: event.modifiers || [] };
+        break;
+    }
+
+    this.events.push(recorded);
+    this.metadata.actionCount = this.events.length;
+    return recorded;
+  }
+
+  /**
+   * Add a DOM snapshot at a key moment
+   */
+  addSnapshot(snapshot) {
+    if (this.status !== 'recording') return;
+    this.snapshots.push({
+      seq: this.snapshots.length,
+      timestamp: Date.now(),
+      url: snapshot.url || '',
+      title: snapshot.title || '',
+      domHash: snapshot.domHash || '',
+      elementCount: snapshot.elementCount || 0,
+      interactiveElements: snapshot.interactiveElements || [],
+    });
+  }
+
+  pause() { if (this.status === 'recording') this.status = 'paused'; }
+  resume() { if (this.status === 'paused') this.status = 'recording'; }
+
+  complete() {
+    this.status = 'completed';
+    this.metadata.completedAt = Date.now();
+    this.metadata.duration = this.metadata.completedAt - this.metadata.startedAt;
+  }
+
+  cancel() {
+    this.status = 'cancelled';
+    this.metadata.completedAt = Date.now();
+  }
+
+  /**
+   * Convert recording to a replayable Recipe
+   */
+  toRecipe() {
+    return {
+      id: crypto.randomUUID(),
+      name: this.name,
+      description: this.description,
+      version: '1.0.0',
+      sourceRecording: this.id,
+      domain: this.metadata.domain,
+      startUrl: this.startUrl,
+      tags: this.metadata.tags,
+      created: new Date().toISOString(),
+      steps: this.events.map(evt => this._eventToStep(evt)),
+      metadata: {
+        recordedBy: this.agentId,
+        duration: this.metadata.duration,
+        pageCount: this.metadata.pageCount,
+        actionCount: this.metadata.actionCount,
+      },
+    };
+  }
+
+  _eventToStep(evt) {
+    const step = {
+      seq: evt.seq,
+      action: evt.type,
+      selector: evt.target.selector,
+      description: this._describeStep(evt),
+      wait: { before: 0, after: 200 }, // Default delays
+      retry: { maxAttempts: 3, delay: 500 },
+      fallback: {},
+    };
+
+    // Add fallback selectors
+    if (evt.target.text) step.fallback.text = evt.target.text;
+    if (evt.target.xpath) step.fallback.xpath = evt.target.xpath;
+    if (evt.target.attributes?.['aria-label']) step.fallback.ariaLabel = evt.target.attributes['aria-label'];
+
+    switch (evt.type) {
+      case 'click':
+        step.options = { button: evt.data.button, doubleClick: evt.data.doubleClick };
+        break;
+      case 'type':
+        step.value = evt.data.value;
+        step.options = { clearFirst: evt.data.clearFirst };
+        break;
+      case 'navigate':
+        step.url = evt.data.url;
+        step.options = { method: evt.data.method };
+        break;
+      case 'scroll':
+        step.options = { x: evt.data.x, y: evt.data.y, direction: evt.data.direction };
+        break;
+      case 'select':
+        step.value = evt.data.value;
+        step.options = { label: evt.data.label };
+        break;
+      case 'wait':
+        step.options = { ms: evt.data.ms, condition: evt.data.condition };
+        break;
+      case 'assert':
+        step.options = { assertion: evt.data.assertion, expected: evt.data.expected };
+        break;
+      case 'keypress':
+        step.options = { key: evt.data.key, modifiers: evt.data.modifiers };
+        break;
+    }
+
+    return step;
+  }
+
+  _describeStep(evt) {
+    const target = evt.target.text ? `"${evt.target.text.slice(0, 50)}"` : evt.target.selector;
+    switch (evt.type) {
+      case 'click': return `Click on ${target}`;
+      case 'type': return `Type "${(evt.data.value || '').slice(0, 30)}" into ${target}`;
+      case 'navigate': return `Navigate to ${evt.data.url}`;
+      case 'scroll': return `Scroll ${evt.data.direction}`;
+      case 'select': return `Select "${evt.data.label || evt.data.value}" in ${target}`;
+      case 'hover': return `Hover over ${target}`;
+      case 'wait': return `Wait ${evt.data.ms}ms`;
+      case 'assert': return `Assert ${evt.data.assertion}`;
+      case 'keypress': return `Press ${evt.data.modifiers?.length ? evt.data.modifiers.join('+') + '+' : ''}${evt.data.key}`;
+      default: return `${evt.type} on ${target}`;
+    }
+  }
+
+  toJSON() {
+    return {
+      id: this.id,
+      name: this.name,
+      description: this.description,
+      agentId: this.agentId,
+      startUrl: this.startUrl,
+      status: this.status,
+      events: this.events,
+      snapshots: this.snapshots,
+      metadata: this.metadata,
+    };
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// RECIPE EXECUTOR — Replays recorded recipes
+// ═══════════════════════════════════════════════════════════════════
+
+class RecipeExecutor {
+  constructor() {
+    this.executions = new Map();
+  }
+
+  /**
+   * Start executing a recipe
+   * Returns an execution plan that can be consumed step-by-step
+   */
+  startExecution(recipe, options = {}) {
+    const execution = {
+      id: crypto.randomUUID(),
+      recipeId: recipe.id,
+      recipeName: recipe.name,
+      status: 'running', // running | paused | completed | failed | aborted
+      currentStep: 0,
+      totalSteps: recipe.steps.length,
+      startedAt: Date.now(),
+      completedAt: null,
+      results: [],
+      variables: options.variables || {},
+      config: {
+        speed: options.speed || 1.0,         // Playback speed multiplier
+        stopOnError: options.stopOnError !== false,
+        skipWaits: !!options.skipWaits,
+        adaptiveSelectors: options.adaptiveSelectors !== false, // Try fallbacks
+        maxRetries: options.maxRetries || 3,
+        humanInTheLoop: !!options.humanInTheLoop, // Pause on sensitive actions
+      },
+      steps: recipe.steps.map(s => ({ ...s })), // Clone steps
+      errors: [],
+    };
+
+    // Variable substitution in steps
+    if (Object.keys(execution.variables).length > 0) {
+      for (const step of execution.steps) {
+        if (step.value) step.value = this._substituteVars(step.value, execution.variables);
+        if (step.url) step.url = this._substituteVars(step.url, execution.variables);
+      }
+    }
+
+    this.executions.set(execution.id, execution);
+    return execution;
+  }
+
+  /**
+   * Get next step to execute
+   */
+  getNextStep(executionId) {
+    const exec = this.executions.get(executionId);
+    if (!exec || exec.status !== 'running') return null;
+    if (exec.currentStep >= exec.totalSteps) {
+      exec.status = 'completed';
+      exec.completedAt = Date.now();
+      return null;
+    }
+
+    const step = exec.steps[exec.currentStep];
+    const sensitiveActions = ['type']; // Actions that might need human approval
+    if (exec.config.humanInTheLoop && sensitiveActions.includes(step.action)) {
+      step._requiresApproval = true;
+    }
+
+    return { ...step, executionId, stepIndex: exec.currentStep };
+  }
+
+  /**
+   * Report step result
+   */
+  reportStepResult(executionId, stepIndex, result) {
+    const exec = this.executions.get(executionId);
+    if (!exec) return null;
+
+    exec.results[stepIndex] = {
+      stepIndex,
+      action: exec.steps[stepIndex]?.action,
+      success: result.success,
+      error: result.error || null,
+      duration: result.duration || 0,
+      timestamp: Date.now(),
+      selectorUsed: result.selectorUsed || exec.steps[stepIndex]?.selector,
+    };
+
+    if (result.success) {
+      exec.currentStep = stepIndex + 1;
+    } else {
+      exec.errors.push({ stepIndex, error: result.error, timestamp: Date.now() });
+      if (exec.config.stopOnError) {
+        exec.status = 'failed';
+        exec.completedAt = Date.now();
+      } else {
+        exec.currentStep = stepIndex + 1;
+      }
+    }
+
+    // Auto-complete if done
+    if (exec.currentStep >= exec.totalSteps && exec.status === 'running') {
+      exec.status = 'completed';
+      exec.completedAt = Date.now();
+    }
+
+    return exec;
+  }
+
+  pauseExecution(executionId) {
+    const exec = this.executions.get(executionId);
+    if (exec && exec.status === 'running') exec.status = 'paused';
+    return exec;
+  }
+
+  resumeExecution(executionId) {
+    const exec = this.executions.get(executionId);
+    if (exec && exec.status === 'paused') exec.status = 'running';
+    return exec;
+  }
+
+  abortExecution(executionId) {
+    const exec = this.executions.get(executionId);
+    if (exec) { exec.status = 'aborted'; exec.completedAt = Date.now(); }
+    return exec;
+  }
+
+  getExecution(executionId) { return this.executions.get(executionId) || null; }
+
+  listExecutions(limit = 50) {
+    return [...this.executions.values()]
+      .sort((a, b) => b.startedAt - a.startedAt)
+      .slice(0, limit);
+  }
+
+  _substituteVars(str, vars) {
+    if (typeof str !== 'string') return str;
+    return str.replace(/\{\{(\w+)\}\}/g, (_, key) => vars[key] !== undefined ? String(vars[key]) : `{{${key}}}`);
+  }
+
+  getStats() {
+    const execs = [...this.executions.values()];
+    return {
+      total: execs.length,
+      running: execs.filter(e => e.status === 'running').length,
+      completed: execs.filter(e => e.status === 'completed').length,
+      failed: execs.filter(e => e.status === 'failed').length,
+    };
+  }
+}
+
+// ═══════════════════════════════════════════════════════════════════
+// LfD ENGINE — Manages recordings, recipes, and executions
+// ═══════════════════════════════════════════════════════════════════
+
+class LfdEngine {
+  constructor() {
+    this.sessions = new Map();    // Active recording sessions
+    this.recipes = new Map();     // Saved recipes
+    this.executor = new RecipeExecutor();
+    this.stats = {
+      totalRecordings: 0,
+      totalRecipes: 0,
+      totalExecutions: 0,
+      totalEvents: 0,
+    };
+  }
+
+  // ── Recording ──
+
+  startRecording(config) {
+    const session = new RecordingSession(config);
+    this.sessions.set(session.id, session);
+    this.stats.totalRecordings++;
+    return { id: session.id, status: session.status, startedAt: session.metadata.startedAt };
+  }
+
+  recordEvent(sessionId, event) {
+    const session = this.sessions.get(sessionId);
+    if (!session) throw new Error('Recording session not found');
+    const recorded = session.addEvent(event);
+    if (recorded) this.stats.totalEvents++;
+    return recorded;
+  }
+
+  recordSnapshot(sessionId, snapshot) {
+    const session = this.sessions.get(sessionId);
+    if (!session) throw new Error('Recording session not found');
+    session.addSnapshot(snapshot);
+  }
+
+  pauseRecording(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session) throw new Error('Recording session not found');
+    session.pause();
+    return { id: sessionId, status: session.status };
+  }
+
+  resumeRecording(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session) throw new Error('Recording session not found');
+    session.resume();
+    return { id: sessionId, status: session.status };
+  }
+
+  stopRecording(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session) throw new Error('Recording session not found');
+    session.complete();
+
+    // Auto-convert to recipe
+    const recipe = session.toRecipe();
+    this.recipes.set(recipe.id, recipe);
+    this.stats.totalRecipes++;
+
+    return { recording: session.toJSON(), recipe };
+  }
+
+  cancelRecording(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session) throw new Error('Recording session not found');
+    session.cancel();
+    return { id: sessionId, status: 'cancelled' };
+  }
+
+  getRecording(sessionId) {
+    const session = this.sessions.get(sessionId);
+    if (!session) return null;
+    return session.toJSON();
+  }
+
+  listRecordings(limit = 50) {
+    return [...this.sessions.values()]
+      .map(s => ({
+        id: s.id, name: s.name, status: s.status, domain: s.metadata.domain,
+        actionCount: s.metadata.actionCount, duration: s.metadata.duration,
+        startedAt: s.metadata.startedAt,
+      }))
+      .sort((a, b) => b.startedAt - a.startedAt)
+      .slice(0, limit);
+  }
+
+  // ── Recipes ──
+
+  saveRecipe(recipe) {
+    if (!recipe.id) recipe.id = crypto.randomUUID();
+    if (!recipe.created) recipe.created = new Date().toISOString();
+    this.recipes.set(recipe.id, recipe);
+    this.stats.totalRecipes++;
+    return recipe;
+  }
+
+  getRecipe(recipeId) { return this.recipes.get(recipeId) || null; }
+
+  listRecipes(filters = {}, limit = 50) {
+    let recipes = [...this.recipes.values()];
+    if (filters.domain) recipes = recipes.filter(r => r.domain === filters.domain);
+    if (filters.tag) recipes = recipes.filter(r => r.tags?.includes(filters.tag));
+    if (filters.query) {
+      const q = filters.query.toLowerCase();
+      recipes = recipes.filter(r =>
+        r.name.toLowerCase().includes(q) || (r.description || '').toLowerCase().includes(q)
+      );
+    }
+    return recipes.sort((a, b) => new Date(b.created) - new Date(a.created)).slice(0, limit);
+  }
+
+  deleteRecipe(recipeId) {
+    return this.recipes.delete(recipeId);
+  }
+
+  // ── Execution ──
+
+  executeRecipe(recipeId, options = {}) {
+    const recipe = this.recipes.get(recipeId);
+    if (!recipe) throw new Error('Recipe not found');
+    this.stats.totalExecutions++;
+    return this.executor.startExecution(recipe, options);
+  }
+
+  getNextStep(executionId) { return this.executor.getNextStep(executionId); }
+  reportStep(executionId, stepIndex, result) { return this.executor.reportStepResult(executionId, stepIndex, result); }
+  pauseExecution(executionId) { return this.executor.pauseExecution(executionId); }
+  resumeExecution(executionId) { return this.executor.resumeExecution(executionId); }
+  abortExecution(executionId) { return this.executor.abortExecution(executionId); }
+  getExecution(executionId) { return this.executor.getExecution(executionId); }
+  listExecutions(limit) { return this.executor.listExecutions(limit); }
+
+  // ── Stats ──
+
+  getStats() {
+    return {
+      ...this.stats,
+      activeRecordings: [...this.sessions.values()].filter(s => s.status === 'recording').length,
+      savedRecipes: this.recipes.size,
+      executorStats: this.executor.getStats(),
+    };
+  }
+
+  /**
+   * Client-side recording script — inject into pages to capture user actions
+   */
+  getRecordingScript(sessionId, serverUrl) {
+    return `(function(){
+  var SID='${sessionId}',API='${serverUrl || ''}/api/os/lfd';
+  var q=[];var sending=false;
+
+  function send(evt){
+    evt.url=location.href;evt.pageTitle=document.title;
+    if(API){
+      q.push(evt);if(!sending){flush();}
+    }
+  }
+
+  function flush(){
+    if(q.length===0){sending=false;return;}
+    sending=true;var batch=q.splice(0,10);
+    fetch(API+'/'+SID+'/events',{method:'POST',headers:{'Content-Type':'application/json'},
+      body:JSON.stringify({events:batch})}).catch(function(){}).finally(function(){setTimeout(flush,100);});
+  }
+
+  function sel(el){
+    if(!el||el===document)return'body';
+    if(el.id)return'#'+CSS.escape(el.id);
+    var t=el.tagName?.toLowerCase()||'';var c=el.className;
+    if(c&&typeof c==='string'){var cls=c.trim().split(/\\s+/).slice(0,2).map(function(x){return'.'+CSS.escape(x);}).join('');if(cls)t+=cls;}
+    return t||'unknown';
+  }
+
+  function attrs(el){
+    var a={};if(!el||!el.attributes)return a;
+    ['id','class','href','type','name','placeholder','role','aria-label','value','alt'].forEach(function(n){
+      if(el.hasAttribute(n))a[n]=el.getAttribute(n);
+    });return a;
+  }
+
+  function rect(el){if(!el)return{};var r=el.getBoundingClientRect();return{x:Math.round(r.x),y:Math.round(r.y),width:Math.round(r.width),height:Math.round(r.height)};}
+
+  document.addEventListener('click',function(e){
+    send({type:'click',selector:sel(e.target),tag:e.target.tagName?.toLowerCase(),text:(e.target.textContent||'').trim().substring(0,100),
+      attributes:attrs(e.target),rect:rect(e.target),x:e.clientX,y:e.clientY,button:e.button===0?'left':'right'});
+  },true);
+
+  document.addEventListener('input',function(e){
+    if(['INPUT','TEXTAREA','SELECT'].includes(e.target.tagName)){
+      send({type:e.target.tagName==='SELECT'?'select':'type',selector:sel(e.target),tag:e.target.tagName.toLowerCase(),
+        text:(e.target.labels?.[0]?.textContent||e.target.placeholder||'').substring(0,100),
+        attributes:attrs(e.target),rect:rect(e.target),value:e.target.value?.substring(0,200)});
+    }
+  },true);
+
+  document.addEventListener('keydown',function(e){
+    if(['Enter','Escape','Tab','Backspace','Delete'].includes(e.key)||e.ctrlKey||e.metaKey){
+      send({type:'keypress',key:e.key,modifiers:[e.ctrlKey&&'ctrl',e.shiftKey&&'shift',e.altKey&&'alt',e.metaKey&&'meta'].filter(Boolean),
+        selector:sel(e.target),tag:e.target.tagName?.toLowerCase(),attributes:attrs(e.target)});
+    }
+  },true);
+
+  var lastScroll=0;
+  window.addEventListener('scroll',function(){
+    var now=Date.now();if(now-lastScroll<500)return;lastScroll=now;
+    send({type:'scroll',scrollX:window.scrollX,scrollY:window.scrollY,direction:window.scrollY>0?'down':'up'});
+  },true);
+
+  // Navigation detection
+  var lastUrl=location.href;
+  setInterval(function(){if(location.href!==lastUrl){send({type:'navigate',url:location.href,method:'spa'});lastUrl=location.href;}},500);
+
+  console.log('[WAB LfD] Recording started — session '+SID);
+})();`;
+  }
+}
+
+const lfdEngine = new LfdEngine();
+module.exports = { lfdEngine, LfdEngine, RecordingSession, RecipeExecutor };

package/server/services/vision.js

@@ -848,6 +848,295 @@ function getVisionHistory(siteId, { limit, url } = {}) {
   });
 }
 
+// ═══════════════════════════════════════════════════════════════════════
+// LOCAL VISION ENGINE — Self-contained, no external API needed
+// DOM-based element detection, dark pattern analysis, ad detection,
+// layout analysis, accessibility audit — all computed locally.
+// ═══════════════════════════════════════════════════════════════════════
+
+const DARK_PATTERN_SIGNATURES = {
+  confirmshaming: [
+    /no,? i (don'?t|do not) (want|like|need|care)/i,
+    /no thanks,? i (prefer|like|want) (to )?(pay|miss|stay|lose)/i,
+    /i('?d rather|'?ll pass)/i, /keep (paying|losing|missing)/i,
+  ],
+  urgency: [
+    /only \d+ left/i, /limited (time|offer|stock|availability)/i,
+    /hurry|rush|act now|don'?t miss|last chance|expires? (soon|in|today)/i,
+    /\d+ (people|others|users) (are )?(viewing|watching|buying)/i,
+    /selling fast|almost gone/i,
+  ],
+  hiddenCosts: [/service fee|handling fee|processing fee|convenience fee/i, /additional charge|extra charge|booking fee/i],
+  forcedContinuity: [/free trial.*(auto|automatic).*(renew|bill|charge)/i, /will be charged after/i, /cancel anytime.*(before|or)/i],
+  sneakIntoBasket: [/added to (your )?cart|included (in|with) (your )?(order|purchase)/i, /protection plan|warranty|insurance/i],
+  privacyZuckering: [/share (your )?(data|info|details|location|contacts)/i, /personalize/i],
+};
+
+const AD_CLASS_PATTERNS = [
+  /\bad[s]?\b/i, /\badvert/i, /\bsponsor/i, /\bpromo(tion|ted)?\b/i,
+  /\bbanner[\-_]?ad/i, /\bgoogle[\-_]?ad/i, /\bdfp[\-_]/i, /\badsense/i, /\btaboola/i, /\boutbrain/i,
+];
+
+const AD_SIZES = [
+  [728, 90], [300, 250], [336, 280], [160, 600], [320, 50], [970, 250], [300, 600],
+];
+
+/**
+ * Analyze a DOM snapshot locally — no external API calls.
+ * @param {Array} domNodes - Flattened DOM nodes from the extraction script
+ * @param {Object} viewport - { width, height }
+ * @returns {Object} Full analysis result
+ */
+function analyzeLocally(domNodes, viewport = { width: 1280, height: 720 }) {
+  const elements = [];
+  const darkPatterns = [];
+  const adElements = [];
+  const accessibilityIssues = [];
+
+  // Layout detection
+  const layoutRegions = [];
+  const LAYOUT_SELECTORS = {
+    header: ['header', '[role="banner"]'],
+    navigation: ['nav', '[role="navigation"]'],
+    main: ['main', '[role="main"]', 'article'],
+    sidebar: ['aside', '[role="complementary"]'],
+    footer: ['footer', '[role="contentinfo"]'],
+  };
+
+  for (const node of domNodes) {
+    const tag = (node.tag || '').toLowerCase();
+    const cls = (node.attributes?.class || '').toLowerCase();
+    const id = (node.attributes?.id || '').toLowerCase();
+    const role = (node.attributes?.role || '').toLowerCase();
+    const text = (node.text || '').trim();
+    const rect = node.rect || {};
+
+    // ── Element detection ──
+    let elType = null;
+    let confidence = 0;
+
+    if (tag === 'button' || role === 'button' || (tag === 'input' && ['submit', 'button'].includes(node.attributes?.type))) {
+      elType = 'button'; confidence = 0.95;
+    } else if (tag === 'a' && node.attributes?.href) {
+      elType = 'link'; confidence = 0.9;
+    } else if (['input', 'textarea'].includes(tag) || role === 'textbox') {
+      elType = 'input'; confidence = 0.95;
+    } else if (tag === 'select' || role === 'listbox' || role === 'combobox') {
+      elType = 'dropdown'; confidence = 0.9;
+    } else if (tag === 'form' || role === 'form') {
+      elType = 'form'; confidence = 0.85;
+    } else if (['img', 'picture', 'svg', 'video', 'canvas'].includes(tag) || role === 'img') {
+      elType = 'image'; confidence = 0.8;
+    } else if (['nav', 'header', 'footer'].includes(tag) || ['navigation', 'banner', 'contentinfo'].includes(role) || cls.includes('nav') || cls.includes('menu')) {
+      elType = 'nav'; confidence = 0.75;
+    } else if (cls.includes('btn') || cls.includes('button') || cls.includes('cta')) {
+      elType = 'button'; confidence = 0.7;
+    } else if (cls.includes('dropdown') || cls.includes('select')) {
+      elType = 'dropdown'; confidence = 0.65;
+    }
+
+    if (elType) {
+      elements.push({
+        type: elType,
+        label: (text || node.attributes?.placeholder || node.attributes?.['aria-label'] || node.attributes?.alt || '').slice(0, 200),
+        description: `${tag} element${cls ? ' class=' + cls.slice(0, 80) : ''}`,
+        boundingBox: { x: rect.x || 0, y: rect.y || 0, width: rect.width || 0, height: rect.height || 0 },
+        suggestedSelector: node.selector || _buildFallbackSelector(node),
+        confidence,
+        interactable: ['button', 'link', 'input', 'dropdown', 'form'].includes(elType),
+      });
+    }
+
+    // ── Dark pattern detection ──
+    if (text.length > 5) {
+      for (const [patternName, regexes] of Object.entries(DARK_PATTERN_SIGNATURES)) {
+        for (const rx of regexes) {
+          if (rx.test(text)) {
+            darkPatterns.push({ type: patternName, text: text.slice(0, 200), selector: node.selector || '', severity: patternName === 'urgency' ? 'medium' : 'high', confidence: 0.85 });
+            break;
+          }
+        }
+      }
+    }
+
+    // Pre-checked upsell checkbox detection
+    if (tag === 'input' && node.attributes?.type === 'checkbox' && node.attributes?.checked != null) {
+      const lbl = text.toLowerCase();
+      if (/newsletter|marketing|promo|share|partner|third.party|sms|offer/i.test(lbl)) {
+        darkPatterns.push({ type: 'misdirection', text: `Pre-checked: "${text.slice(0, 100)}"`, selector: node.selector || '', severity: 'medium', confidence: 0.9 });
+      }
+    }
+
+    // ── Ad detection ──
+    let isAd = false;
+    for (const rx of AD_CLASS_PATTERNS) {
+      if (rx.test(cls) || rx.test(id)) { isAd = true; break; }
+    }
+    if (!isAd && rect.width && rect.height) {
+      for (const [w, h] of AD_SIZES) {
+        if (Math.abs(rect.width - w) < 10 && Math.abs(rect.height - h) < 10) { isAd = true; break; }
+      }
+    }
+    if (!isAd && tag === 'iframe' && node.attributes?.src) {
+      if (/doubleclick|googlesyndication|adnxs|criteo|taboola|outbrain/i.test(node.attributes.src)) isAd = true;
+    }
+    if (isAd) adElements.push({ tag, selector: node.selector || '', rect, reason: `class/id/size match` });
+
+    // ── Accessibility ──
+    if (tag === 'img' && !node.attributes?.alt) {
+      accessibilityIssues.push({ type: 'missing-alt', severity: 'high', selector: node.selector || '' });
+    }
+    if (['button', 'a', 'input'].includes(tag) && rect.width > 0 && (rect.width < 44 || rect.height < 44)) {
+      accessibilityIssues.push({ type: 'small-tap-target', severity: 'medium', selector: node.selector || '', size: `${rect.width}x${rect.height}` });
+    }
+    if (['input', 'select', 'textarea'].includes(tag) && !node.attributes?.['aria-label'] && !node.attributes?.['aria-labelledby'] && !node.attributes?.id) {
+      accessibilityIssues.push({ type: 'missing-label', severity: 'high', selector: node.selector || '' });
+    }
+
+    // ── Layout regions ──
+    for (const [regionName, selectors] of Object.entries(LAYOUT_SELECTORS)) {
+      if (selectors.some(s => {
+        if (s.startsWith('[role="')) return role === s.match(/\[role="(.+?)"\]/)?.[1];
+        return tag === s;
+      })) {
+        layoutRegions.push({ type: regionName, tag, rect, selector: node.selector || '' });
+        break;
+      }
+    }
+  }
+
+  // Build analysis text (human-readable summary for caching)
+  const analysisText = JSON.stringify({
+    summary: {
+      totalElements: elements.length,
+      buttons: elements.filter(e => e.type === 'button').length,
+      links: elements.filter(e => e.type === 'link').length,
+      inputs: elements.filter(e => e.type === 'input').length,
+      forms: elements.filter(e => e.type === 'form').length,
+      darkPatterns: darkPatterns.length,
+      ads: adElements.length,
+      accessibilityIssues: accessibilityIssues.length,
+    },
+    elements,
+    darkPatterns,
+    ads: adElements,
+    accessibility: {
+      issues: accessibilityIssues,
+      score: Math.max(0, 100 - accessibilityIssues.length * 5),
+    },
+    layout: { regions: layoutRegions, columns: layoutRegions.filter(r => r.type === 'sidebar').length > 0 ? 2 : 1 },
+  });
+
+  return {
+    text: analysisText,
+    tokens: 0, // Local analysis — no tokens used
+    elements,
+    darkPatterns,
+    ads: adElements,
+    accessibility: { issues: accessibilityIssues, score: Math.max(0, 100 - accessibilityIssues.length * 5) },
+    layout: { regions: layoutRegions },
+  };
+}
+
+function _buildFallbackSelector(node) {
+  const tag = node.tag || 'div';
+  if (node.attributes?.id) return '#' + node.attributes.id;
+  let s = tag;
+  if (node.attributes?.class) {
+    const cls = node.attributes.class.trim().split(/\s+/).slice(0, 2).join('.');
+    if (cls) s += '.' + cls;
+  }
+  return s;
+}
+
+/**
+ * DOM Extraction Script — inject into pages to capture DOM for local analysis.
+ * Returns minimal JSON with all interactive/layout elements + computed styles.
+ */
+function getDomExtractionScript() {
+  return `(function(){
+  var MAX_D=8,INT=new Set(['a','button','input','select','textarea','details','summary','label']),
+    LAY=new Set(['header','nav','main','aside','footer','article','section','div','form']),
+    SKIP=new Set(['script','style','noscript','meta','link','br','hr']);
+  function ext(el,d){
+    if(d>MAX_D)return null;var t=el.tagName;if(!t)return null;t=t.toLowerCase();
+    if(SKIP.has(t))return null;var r=el.getBoundingClientRect();
+    if(r.width===0&&r.height===0&&!LAY.has(t)&&!INT.has(t))return null;
+    var cs=window.getComputedStyle(el);if(cs.display==='none'||cs.visibility==='hidden')return null;
+    var n={tag:t,text:(el.textContent||'').trim().substring(0,200),selector:sel(el),attributes:{},
+      rect:{x:Math.round(r.x),y:Math.round(r.y),width:Math.round(r.width),height:Math.round(r.height)},
+      visible:r.width>0&&r.height>0&&cs.opacity!=='0'};
+    ['id','class','href','src','alt','type','name','value','placeholder','role','aria-label',
+     'aria-labelledby','aria-checked','data-action','checked','disabled'].forEach(function(a){
+      if(el.hasAttribute(a))n.attributes[a]=el.getAttribute(a);
+    });if(el.checked)n.attributes.checked='checked';
+    if(LAY.has(t)||INT.has(t)){n.children=[];for(var c of el.children){var cn=ext(c,d+1);if(cn)n.children.push(cn);}}
+    return n;
+  }
+  function sel(el){if(el.id)return'#'+CSS.escape(el.id);var p=[];var c=el;
+    for(var i=0;i<4&&c&&c!==document.body;i++){var s=c.tagName.toLowerCase();
+      if(c.id){p.unshift('#'+CSS.escape(c.id));break;}
+      if(c.className&&typeof c.className==='string'){var cl=c.className.trim().split(/\\s+/).slice(0,2).map(function(x){return'.'+CSS.escape(x);}).join('');if(cl)s+=cl;}
+      p.unshift(s);c=c.parentElement;}return p.join(' > ');}
+  function flat(n,r){if(!n)return;var ch=n.children;delete n.children;r.push(n);if(ch)ch.forEach(function(c){flat(c,r);});}
+  var root=ext(document.body,0);var f=[];flat(root,f);
+  return JSON.stringify({url:location.href,title:document.title,viewport:{width:innerWidth,height:innerHeight},dom:f,
+    meta:{lang:document.documentElement.lang||'',charset:document.characterSet}});
+})();`;
+}
+
+// ═══════════════════════════════════════════════════════════════════════
+// Enhanced analyzeScreenshot — use local engine when provider is 'local'
+// and DOM data is provided (no external API call needed)
+// ═══════════════════════════════════════════════════════════════════════
+
+async function analyzePageDOM(siteId, { domSnapshot, url } = {}) {
+  if (!domSnapshot || !domSnapshot.dom) throw new Error('domSnapshot with dom array is required');
+
+  const dataStr = JSON.stringify(domSnapshot.dom).slice(0, 2000);
+  const screenshotHash = crypto.createHash('sha256').update(dataStr).digest('hex');
+
+  // Check cache
+  const cached = stmts.getCacheByHash.get(siteId, screenshotHash);
+  if (cached) {
+    let elements = [];
+    try { elements = JSON.parse(cached.elements_found || '[]'); } catch {}
+    return { analysis: cached.analysis, elements, cached: true, latency_ms: cached.latency_ms, tokens_used: 0, cache_id: cached.id };
+  }
+
+  const startTime = Date.now();
+  const result = analyzeLocally(domSnapshot.dom || [], domSnapshot.viewport);
+  const latencyMs = Date.now() - startTime;
+
+  const cacheId = uuidv4();
+  const config = stmts.getConfig.get(siteId);
+  const cacheTtl = config?.cache_ttl || 300;
+  const expiresAt = new Date(Date.now() + cacheTtl * 1000).toISOString();
+
+  stmts.insertCache.run(cacheId, siteId, url || domSnapshot.url || null, screenshotHash, result.text, JSON.stringify(result.elements), 'local', 'dom-engine', 0, latencyMs, expiresAt);
+
+  const insertElements = db.transaction((elems) => {
+    for (const el of elems) {
+      stmts.insertElement.run(uuidv4(), cacheId, siteId, el.type, el.label, el.description, JSON.stringify(el.boundingBox), el.suggestedSelector, el.confidence, el.interactable ? 1 : 0);
+    }
+  });
+  insertElements(result.elements);
+
+  return {
+    analysis: result.text,
+    elements: result.elements,
+    darkPatterns: result.darkPatterns,
+    ads: result.ads,
+    accessibility: result.accessibility,
+    layout: result.layout,
+    cached: false,
+    latency_ms: latencyMs,
+    tokens_used: 0,
+    cache_id: cacheId,
+    engine: 'local-dom',
+  };
+}
+
 // ═══════════════════════════════════════════════════════════════════════
 // Exports
 // ═══════════════════════════════════════════════════════════════════════
@@ -856,6 +1145,9 @@ module.exports = {
   configureVision,
   getVisionConfig,
   analyzeScreenshot,
+  analyzePageDOM,
+  analyzeLocally,
+  getDomExtractionScript,
   buildVisionPrompt,
   parseVisionResponse,
   extractElementsFromAnalysis,