crawlforge-mcp-server 5.0.2 → 5.0.4

package/CLAUDE.md

@@ -62,7 +62,7 @@ These guidelines are working if: fewer unnecessary changes in diffs, fewer rewri
 
 CrawlForge MCP Server - A professional MCP (Model Context Protocol) server providing 27 web scraping, crawling, and content processing tools (5 inline + 22 advanced).
 
-**Current Version:** 5.0.2
+**Current Version:** 5.0.4
 
 ## Development Commands
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "crawlforge-mcp-server",
-  "version": "5.0.2",
+  "version": "5.0.4",
   "mcpName": "io.github.mysleekdesigns/crawlforge-mcp-server",
   "description": "CrawlForge MCP Server - Professional Model Context Protocol server with 27 web scraping, crawling, deep-research, and autonomous-extraction tools. Returns clean Markdown and structured JSON for Claude, Cursor, and any MCP client. Defaults to local Ollama for LLM extraction (no API key needed); OpenAI/Anthropic available as opt-in. Includes a unified multi-format scrape tool, an autonomous agent, pre-built site templates, and Camoufox stealth browsing.",
   "main": "server.js",

package/server.js

@@ -794,6 +794,8 @@ registerToolIfEnabled("scrape_with_actions", {
       distance: z.number().min(0).optional().describe("scroll: pixels to scroll"),
       smooth: z.boolean().optional().describe("scroll: smooth scrolling"),
       toElement: z.string().optional().describe("scroll: selector to scroll to"),
+      x: z.number().min(0).optional().describe("scroll: absolute X coordinate to scroll to (window.scrollTo; with y, takes precedence over direction/distance)"),
+      y: z.number().min(0).optional().describe("scroll: absolute Y coordinate to scroll to (window.scrollTo; with x, takes precedence over direction/distance)"),
       // screenshot
       fullPage: z.boolean().optional().describe("screenshot: capture full page"),
       quality: z.number().min(0).max(100).optional().describe("screenshot: jpeg quality"),
@@ -1299,8 +1301,8 @@ registerToolIfEnabled("localization", {
       extraHTTPHeaders: z.record(z.string()).optional(),
       userAgent: z.string().optional()
     }).optional().describe("Browser context options for locale emulation"),
-    content: z.string().optional().describe("Content for auto-detection of language and locale"),
-    url: z.string().url().optional().describe("URL for geo-blocking detection or auto-detection"),
+    content: z.string().optional().describe("Page content (HTML or plain text) to analyze — required for auto_detect; no fetching is performed"),
+    url: z.string().url().optional().describe("URL — required for handle_geo_blocking; for auto_detect it is optional metadata used only as a TLD country hint (the page is never fetched)"),
     response: z.object({
       status: z.number(),
       body: z.string().optional(),
@@ -1336,7 +1338,7 @@ registerToolIfEnabled("localization", {
         result = await localizationManager.detectGeoBlocking(params.url, params.response);
         break;
       case 'auto_detect':
-        if (!params.content || !params.url) throw new Error('content and url are required for auto_detect operation');
+        if (!params.content) throw new Error('content is required for auto_detect operation');
         result = await localizationManager.autoDetectLocalization(params.content, params.url);
         break;
       case 'get_stats':

package/src/cli/commands/llmstxt.js

@@ -10,17 +10,24 @@ export function register(program) {
     .command('llmstxt <url>')
     .description('Generate llms.txt for a website (AI compliance file)')
     .option('--include-full', 'Also generate llms-full.txt')
-    .option('--max-pages <n>', 'Maximum pages to analyze', '50')
+    .option('--max-pages <n>', 'Maximum pages to analyze, 10-500', '50')
     .action(async (url, opts, cmd) => {
       const globals = cmd.parent.opts();
       const cliFlags = { json: globals.json, pretty: globals.pretty, quiet: globals.quiet };
+      // GenerateLLMsTxtSchema requires analysisOptions.maxPages between 10 and 500 —
+      // validate here so users get a clear message instead of a raw zod error.
+      const maxPages = parseInt(opts.maxPages, 10);
+      if (!Number.isInteger(maxPages) || maxPages < 10 || maxPages > 500) {
+        process.stderr.write('Error: --max-pages must be between 10 and 500\n');
+        process.exit(1);
+      }
       const tool = new GenerateLLMsTxtTool(getToolConfig('generate_llms_txt'));
       // GenerateLLMsTxtSchema expects: url, format ('both'|'llms-txt'|'llms-full-txt'),
       // analysisOptions.maxPages.
       await runTool(tool, {
         url,
         format: opts.includeFull ? 'both' : 'llms-txt',
-        analysisOptions: { maxPages: parseInt(opts.maxPages, 10) }
+        analysisOptions: { maxPages }
       }, cliFlags);
     });
 }

package/src/constants/config.js

@@ -303,7 +303,11 @@ export function validateConfig() {
 export function getToolConfig(toolName) {
   const toolConfigs = {
     search_web: {
-      apiKey: config.crawlforge.apiKey,
+      // Read env at call time, not import time: the CLI resolves the key
+      // (--api-key flag / env / ~/.crawlforge/config.json) in a preAction
+      // hook that runs AFTER this module was imported, so the frozen
+      // config.crawlforge.apiKey snapshot misses stored keys.
+      apiKey: process.env.CRAWLFORGE_API_KEY || config.crawlforge.apiKey,
       apiBaseUrl: config.crawlforge.apiBaseUrl,
       
       // Common configuration

package/src/core/ActionExecutor.js

@@ -72,7 +72,12 @@ const ScrollActionSchema = BaseActionSchema.extend({
   direction: z.enum(['up', 'down', 'left', 'right']).default('down'),
   distance: z.number().min(0).default(100),
   smooth: z.boolean().default(true),
-  toElement: z.string().optional()
+  toElement: z.string().optional(),
+  // Absolute scroll-to coordinates (window.scrollTo). When present they take
+  // precedence over direction/distance. Matches the CLI guide's documented
+  // action-script format: { "type": "scroll", "x": 0, "y": 500 }.
+  x: z.number().min(0).optional(),
+  y: z.number().min(0).optional()
 });
 
 const ScreenshotActionSchema = BaseActionSchema.extend({
@@ -708,6 +713,20 @@ export class ActionExecutor extends EventEmitter {
       return { scrolledToElement: action.toElement };
     }
 
+    // Absolute scroll-to coordinates take precedence over direction/distance.
+    // window.scrollTo (not scrollBy/mouse.wheel, which are relative deltas) is
+    // the standard Playwright pattern for absolute positioning. A missing axis
+    // defaults to 0, matching the plain window.scrollTo(x, y) call form.
+    if (action.x !== undefined || action.y !== undefined) {
+      const targetX = action.x ?? 0;
+      const targetY = action.y ?? 0;
+      await page.evaluate(
+        ([x, y]) => window.scrollTo(x, y),
+        [targetX, targetY]
+      );
+      return { scrolledTo: { x: targetX, y: targetY }, mode: 'absolute' };
+    }
+
     if (humanBehaviorSimulator) {
       // Use human-like scrolling behavior
       await humanBehaviorSimulator.simulateScroll(page, {

package/src/core/AgentOrchestrator.js

@@ -175,9 +175,20 @@ export class AgentOrchestrator {
     let searchQueries = [prompt]; // fallback: use raw prompt as query
     try {
       const planPrompt =
-        `Decompose this research task into 1-3 concise web search queries (one per line, no bullets):\n\n${prompt}`;
+        `Decompose this research task into 1-3 concise web search queries. ` +
+        `Output ONLY the queries, one per line, no preamble or numbering:\n\n${prompt}`;
       const { text } = await this._getSamplingClient().complete(planPrompt, { maxTokens: 200 });
-      const lines = text.split('\n').map(l => l.replace(/^[-*\d.)\s]+/, '').trim()).filter(Boolean);
+      const lines = text.split('\n')
+        .map(l => l.replace(/^[-*\d.)\s]+/, '').trim())
+        .filter(Boolean)
+        // Drop preamble/garbage lines ("Here are 3 concise web search queries:", …)
+        // so they never become search query #1 and poison the URL queue.
+        .filter(l =>
+          !l.endsWith(':') &&
+          !/^here (are|is)\b/i.test(l) &&
+          !/search quer(y|ies)/i.test(l) &&
+          l.length <= 100
+        );
       if (lines.length > 0) searchQueries = lines.slice(0, 3);
     } catch {
       // Sampling unavailable — use raw prompt
@@ -185,6 +196,18 @@ export class AgentOrchestrator {
 
     // ── GATHER (search) ───────────────────────────────────────────────────────
     const urlQueue = [...seedUrls]; // start with any user-provided seeds
+    // Sites named directly in the prompt (full URLs or bare domains like
+    // "news.ycombinator.com") are the most authoritative sources for the task —
+    // queue them ahead of search results.
+    const namedSites = prompt.match(/https?:\/\/[^\s"'<>]+|(?<![\w.@/-])[a-z0-9][\w-]*(?:\.[a-z0-9][\w-]*)*\.[a-z]{2,}(?![\w-])/gi) || [];
+    // Seeds and prompt-named sites also outrank search results at SHAPE time
+    // (see priorityUrls below) — generic term overlap must not bury them.
+    const priorityUrls = [...seedUrls];
+    for (const site of namedSites) {
+      const url = (/^https?:\/\//i.test(site) ? site : `https://${site}`).replace(/[.,;:!?)]+$/, '');
+      if (!urlQueue.includes(url)) urlQueue.push(url);
+      if (!priorityUrls.includes(url)) priorityUrls.push(url);
+    }
     const searchResults = [];
 
     if (urlQueue.length < capUrls) {
@@ -227,8 +250,10 @@ export class AgentOrchestrator {
         const { textContent, finalUrl } = await fetchAndParse(url, { timeoutMs: 10000 });
         if (!isRelevant(textContent, prompt)) continue;
         step++;
+        const sr = searchResults.find(s => s.url === url);
         evidence.push({
           url: finalUrl,
+          title: sr ? sr.title : '',
           text: truncate(textContent),
           step
         });
@@ -236,7 +261,26 @@ export class AgentOrchestrator {
     }
 
     // ── SHAPE ─────────────────────────────────────────────────────────────────
-    const combinedText = evidence.map(e => `--- Source: ${e.url} ---\n${e.text}`).join('\n\n');
+    // Order evidence by simple relevance to the prompt (term overlap with
+    // url+title+text) instead of raw queue order, then give every source a
+    // per-source slice of the synthesis budget so no source is silently cut off.
+    const promptTerms = prompt.toLowerCase().split(/\s+/).filter(t => t.length > 3);
+    // Seeds/prompt-named sites get a fixed boost above any term-overlap score:
+    // a generic article mentioning the task's words ("title", "story") must
+    // never outrank the source the user explicitly pointed at (live retest
+    // 2026-08-20: an NFL article buried the named news.ycombinator.com page).
+    const isPriority = url => priorityUrls.some(p => url === p || url.startsWith(`${p}/`) || `${url}/` === p);
+    const orderedEvidence = evidence
+      .map(e => ({
+        ...e,
+        _score: (isPriority(e.url) ? 1000 : 0) +
+          promptTerms.filter(t => `${e.url} ${e.title || ''} ${e.text}`.toLowerCase().includes(t)).length
+      }))
+      .sort((a, b) => b._score - a._score);
+    const perSourceCap = Math.max(1500, Math.floor(12000 / Math.max(evidence.length, 1)));
+    const combinedText = orderedEvidence
+      .map(e => `--- Source: ${e.url} ---\n${truncate(e.text, perSourceCap)}`)
+      .join('\n\n');
 
     if (!combinedText.trim()) {
       return {
@@ -283,10 +327,20 @@ export class AgentOrchestrator {
     let degradedReason;
 
     try {
+      // Wording matters for small local models (llama3.2-class): without the
+      // "already fetched / do not refuse" framing they answer "I cannot access
+      // the internet" or "the sources do not contain it" even when the answer
+      // sits in the first source (live retest 2026-08-20).
       const synthesisPrompt =
-        `You are a research assistant. Based on the sources below, answer this task:\n\n` +
+        `You are a data-extraction assistant. The web sources below have ALREADY been fetched for you and their text is included — no internet access is needed; do not refuse for lack of browsing ability. They are ordered most-relevant first. Answer the task using ONLY this source text:\n\n` +
         `Task: ${prompt}\n\n` +
-        `${truncate(combinedText, 12000)}\n\n` +
+        `${combinedText}\n\n` +
+        `Rules:\n` +
+        `- Answer ONLY from the provided sources; do not use outside knowledge.\n` +
+        `- Read the sources carefully before concluding anything is missing from them.\n` +
+        `- Cite the exact source URL(s) you used.\n` +
+        `- If, after careful reading, the sources genuinely do not contain the answer, say so explicitly.\n` +
+        `- NEVER invent or guess a URL; cite only URLs that appear in the sources above.\n\n` +
         `Provide a clear, concise answer.`;
 
       const { text } = await this._getSamplingClient().complete(synthesisPrompt, { maxTokens: 1024 });

package/src/core/ChangeTracker.js

@@ -211,12 +211,14 @@ export class ChangeTracker extends EventEmitter {
       // Calculate change significance
       const significance = await this.calculateChangeSignificance(changeAnalysis, baseline.options);
       
-      // Create change record
+      // Create change record. An unchanged compare (significance 'none' ⇒
+      // hasChanges:false) must report a neutral changeType — classifyChangeType
+      // falls through to 'text_change' even when nothing changed at all.
       const changeRecord = {
         url,
         timestamp: Date.now(),
         baselineVersion: baseline.version,
-        changeType: this.classifyChangeType(changeAnalysis),
+        changeType: significance === 'none' ? 'none' : this.classifyChangeType(changeAnalysis),
         significance,
         details: changeAnalysis,
         metrics: {
@@ -742,12 +744,17 @@ export class ChangeTracker extends EventEmitter {
       currentContent = currentContent.toLowerCase();
     }
     
-    // Word-level diff
+    // Word-level diff. Only record an entry when something actually changed
+    // (mirrors line_diff below) — unconditionally pushing an empty word_diff
+    // made every unchanged compare report "Text content changed".
     const wordDiff = diffWords(baselineContent, currentContent);
-    textChanges.push({
-      type: 'word_diff',
-      changes: wordDiff.filter(part => part.added || part.removed)
-    });
+    const wordDiffChanges = wordDiff.filter(part => part.added || part.removed);
+    if (wordDiffChanges.length > 0) {
+      textChanges.push({
+        type: 'word_diff',
+        changes: wordDiffChanges
+      });
+    }
     
     // Line-level diff for structured content
     const lineDiff = diffLines(baselineContent, currentContent);
@@ -903,18 +910,23 @@ export class ChangeTracker extends EventEmitter {
     
     const tagSimilarity = this.calculateTagSimilarity(baselineElements, currentElements);
     const hierarchySimilarity = this.calculateHierarchySimilarity(baseline.hierarchy, current.hierarchy);
-    
-    return (tagSimilarity + hierarchySimilarity) / 2;
+
+    // Clamp defensively — this is a 0-1 metric and must never leave that range.
+    return Math.max(0, Math.min(1, (tagSimilarity + hierarchySimilarity) / 2));
   }
-  
+
   calculateTagSimilarity(baselineElements, currentElements) {
-    const baselineTags = baselineElements.map(el => el.tag);
-    const currentTags = currentElements.map(el => el.tag);
-    
-    const intersection = baselineTags.filter(tag => currentTags.includes(tag));
+    // Jaccard similarity: intersection and union must both operate on SETS.
+    // The old code intersected the raw (duplicate-laden) tag list against a
+    // set union, so repeated tags (div, p, ...) inflated the numerator and
+    // produced impossible scores > 1 (e.g. the observed 1.05).
+    const baselineTags = new Set(baselineElements.map(el => el.tag));
+    const currentTags = new Set(currentElements.map(el => el.tag));
+
+    const intersection = [...baselineTags].filter(tag => currentTags.has(tag));
     const union = new Set([...baselineTags, ...currentTags]);
-    
-    return intersection.length / union.size;
+
+    return union.size === 0 ? 1 : intersection.length / union.size;
   }
   
   calculateHierarchySimilarity(baseline, current) {

package/src/core/LocalizationManager.js

@@ -548,7 +548,7 @@ export class LocalizationManager extends EventEmitter {
   /**
    * Auto-detect appropriate localization from content
    * @param {string} content - Web page content
-   * @param {string} url - Source URL
+   * @param {string} [url] - Optional source URL (used only as a TLD country hint)
    * @returns {Object} - Detected localization settings
    */
   async autoDetectLocalization(content, url) {
@@ -698,14 +698,40 @@ export class LocalizationManager extends EventEmitter {
   }
   
   getDateFormat(countryCode) {
+    // Audited against CLDR short-date patterns / Wikipedia "List of date
+    // formats by country". Covers every SUPPORTED_COUNTRIES entry; the
+    // fallback is DD/MM/YYYY (day-first), which most of the world uses —
+    // MM/DD/YYYY is essentially US-only.
     const formats = {
       'US': 'MM/DD/YYYY',
       'GB': 'DD/MM/YYYY',
       'DE': 'DD.MM.YYYY',
-      'JP': 'YYYY/MM/DD'
+      'FR': 'DD/MM/YYYY',
+      'JP': 'YYYY/MM/DD',
+      'CN': 'YYYY/MM/DD',
+      'AU': 'DD/MM/YYYY',
+      'CA': 'YYYY-MM-DD',
+      'IT': 'DD/MM/YYYY',
+      'ES': 'DD/MM/YYYY',
+      'RU': 'DD.MM.YYYY',
+      'BR': 'DD/MM/YYYY',
+      'IN': 'DD/MM/YYYY',
+      'KR': 'YYYY.MM.DD',
+      'MX': 'DD/MM/YYYY',
+      'NL': 'DD-MM-YYYY',
+      'SE': 'YYYY-MM-DD',
+      'NO': 'DD.MM.YYYY',
+      'SA': 'DD/MM/YYYY',
+      'AE': 'DD/MM/YYYY',
+      'TR': 'DD.MM.YYYY',
+      'IL': 'DD.MM.YYYY',
+      'TH': 'DD/MM/YYYY',
+      'SG': 'DD/MM/YYYY',
+      'PL': 'DD.MM.YYYY',
+      'ZA': 'YYYY/MM/DD'
     };
-    
-    return formats[countryCode] || 'MM/DD/YYYY';
+
+    return formats[countryCode] || 'DD/MM/YYYY';
   }
   
   getNumberFormat(countryCode) {
@@ -1275,7 +1301,17 @@ export class LocalizationManager extends EventEmitter {
       const detectedLang = await this.analyzeTextLanguage(textSample);
       if (detectedLang) {
         detection.evidence.push(`Text analysis: ${detectedLang.language} (${detectedLang.confidence}%)`);
-        detection.confidence += detectedLang.confidence / 100 * 0.2;
+        if (!detection.detectedLanguage) {
+          // Text analysis is the primary (only) language evidence — use it as
+          // the detected language, weighted strongly. Previously the result
+          // was pushed to evidence but detectedLanguage stayed null and the
+          // 0.2 corroboration weight left confidence near zero.
+          detection.detectedLanguage = detectedLang.language;
+          detection.confidence += detectedLang.confidence / 100 * 0.6;
+        } else {
+          // Corroborates (or contradicts) HTML/meta evidence — lower weight
+          detection.confidence += detectedLang.confidence / 100 * 0.2;
+        }
       }
     }
   }
@@ -1347,15 +1383,22 @@ export class LocalizationManager extends EventEmitter {
     
     let bestMatch = null;
     let maxMatches = 0;
-    
+    const wordCount = text.split(/\s+/).filter(Boolean).length;
+
     for (const [lang, pattern] of Object.entries(patterns)) {
       const matches = (text.match(pattern) || []).length;
       if (matches > maxMatches) {
         maxMatches = matches;
-        bestMatch = { language: lang, confidence: Math.min(95, matches * 5) };
+        // Confidence from stop-word DENSITY (matches per word), not the
+        // absolute match count — absolute counts made confidence depend on
+        // sample length (a 500-char English sample scored only ~35%).
+        // Stop-words are ~25-40% of natural text in the matching language,
+        // so density * 250 puts an unambiguous match in the 60-95 range.
+        const density = matches / Math.max(1, wordCount);
+        bestMatch = { language: lang, confidence: Math.min(95, Math.round(density * 250)) };
       }
     }
-    
+
     return bestMatch;
   }
 
@@ -1363,15 +1406,17 @@ export class LocalizationManager extends EventEmitter {
    * Enhanced country detection
    */
   async performCountryDetection(content, url, detection) {
-    // TLD analysis
-    const urlObj = new URL(url);
-    const tldMatch = urlObj.hostname.match(/\.([a-z]{2})$/);
-    if (tldMatch) {
-      const tld = tldMatch[1].toUpperCase();
-      if (SUPPORTED_COUNTRIES[tld]) {
-        detection.detectedCountry = tld;
-        detection.evidence.push(`TLD suggests country: ${tld}`);
-        detection.confidence += 0.2;
+    // TLD analysis — url is optional metadata; content-only detection skips it
+    if (url) {
+      const urlObj = new URL(url);
+      const tldMatch = urlObj.hostname.match(/\.([a-z]{2})$/);
+      if (tldMatch) {
+        const tld = tldMatch[1].toUpperCase();
+        if (SUPPORTED_COUNTRIES[tld]) {
+          detection.detectedCountry = tld;
+          detection.evidence.push(`TLD suggests country: ${tld}`);
+          detection.confidence += 0.2;
+        }
       }
     }
     

package/src/core/MonitorStore.js

@@ -1,18 +1,28 @@
 /**
  * MonitorStore — disk persistence for scheduled change-monitors.
  *
- * One JSON file per monitor under ./monitors/<id>.json. Mirrors JobManager's
- * persistence *pattern* (mkdir-recursive, per-file JSON, randomUUID, load-on-
- * start) but deliberately omits TTL/eviction — scheduled monitors are long-lived
- * and must never be auto-expired.
+ * One JSON file per monitor under <os.homedir()>/.crawlforge/monitors/<id>.json
+ * (same base dir as ~/.crawlforge/config.json and ~/.crawlforge/snapshots —
+ * user state must never depend on process.cwd(), or monitor:create from dir X
+ * and monitor:stop / monitor:run-due from dir Y silently see different stores).
+ * Mirrors JobManager's persistence *pattern* (mkdir-recursive, per-file JSON,
+ * randomUUID, load-on-start) but deliberately omits TTL/eviction — scheduled
+ * monitors are long-lived and must never be auto-expired.
  */
 import { promises as fs } from 'node:fs';
+import os from 'node:os';
 import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 
 export class MonitorStore {
-  constructor({ storageDir = './monitors' } = {}) {
-    this.storageDir = storageDir;
+  constructor({ storageDir, legacyDir } = {}) {
+    this.storageDir = storageDir || path.join(os.homedir(), '.crawlforge', 'monitors');
+    // One-time best-effort migration source for stores created before v5.0.3,
+    // when the default was cwd-relative './monitors'. Only armed when the
+    // caller did NOT override storageDir (i.e. the default upgrade path), so
+    // tests and embedders with explicit dirs never sweep files out of cwd —
+    // unless they opt in by passing legacyDir explicitly.
+    this._legacyDir = legacyDir ?? (storageDir ? null : path.resolve('./monitors'));
     this.monitors = new Map();
     this._loaded = false;
   }
@@ -33,10 +43,49 @@ export class MonitorStore {
     } catch {
       /* dir unavailable — start empty */
     }
+    await this._migrateLegacyDir();
     this._loaded = true;
     return this.monitors;
   }
 
+  /**
+   * Best-effort, idempotent migration of a legacy cwd-relative './monitors'
+   * store into the new home-rooted store. Moves each parseable monitor file
+   * whose id is not already present; skips (and leaves in place) everything
+   * else. Never throws — a failed migration must not break monitor loading.
+   */
+  async _migrateLegacyDir() {
+    if (!this._legacyDir) return;
+    try {
+      if (path.resolve(this._legacyDir) === path.resolve(this.storageDir)) return;
+      const files = await fs.readdir(this._legacyDir); // throws if absent — caught below
+      for (const f of files) {
+        if (!f.endsWith('.json')) continue;
+        const from = path.join(this._legacyDir, f);
+        try {
+          const def = JSON.parse(await fs.readFile(from, 'utf8'));
+          if (!def || !def.id || this.monitors.has(def.id)) continue; // skip existing ids
+          await fs.mkdir(this.storageDir, { recursive: true });
+          const to = path.join(this.storageDir, `${def.id}.json`);
+          try {
+            await fs.rename(from, to);
+          } catch {
+            // rename fails across filesystems (EXDEV) — copy+unlink instead
+            await fs.copyFile(from, to);
+            await fs.unlink(from).catch(() => {});
+          }
+          this.monitors.set(def.id, def);
+        } catch {
+          /* unreadable/corrupt legacy file — leave it, keep going */
+        }
+      }
+      // Tidy up the legacy dir only if the migration emptied it.
+      await fs.rmdir(this._legacyDir).catch(() => {});
+    } catch {
+      /* no legacy dir (the common case) or unreadable — nothing to migrate */
+    }
+  }
+
   newId() {
     return randomUUID();
   }

package/src/core/ResearchOrchestrator.js

@@ -903,8 +903,12 @@ export class ResearchOrchestrator extends EventEmitter {
   /** One stealth navigation. Fresh page/context; judges blocked by rendered content. */
   async _stealthFetchOnce(url) {
     let page;
+    let camoufoxContext;
     if (this._stealthEngineActive === 'camoufox') {
-      page = await this._stealthBrowser.newPage();
+      // viewport:null skips Browser.setDefaultViewport, whose playwright-core
+      // 1.62 payload (isMobile etc.) camoufox's older Firefox build rejects.
+      camoufoxContext = await this._stealthBrowser.newContext({ viewport: null });
+      page = await camoufoxContext.newPage();
     } else {
       const { contextId } = await this._stealthManager.createStealthContext({ level: this.stealthLevel });
       page = await this._stealthManager.createStealthPage(contextId);
@@ -930,6 +934,7 @@ export class ResearchOrchestrator extends EventEmitter {
       return html && html.length > 200 ? html : null;
     } finally {
       await page.close().catch(() => {});
+      if (camoufoxContext) await camoufoxContext.close().catch(() => {});
     }
   }
 

package/src/core/StealthBrowserManager.js

@@ -421,6 +421,20 @@ export class StealthBrowserManager {
       javaScriptEnabled: true
     };
 
+    // camoufox's Firefox build predates the Browser.setDefaultViewport fields
+    // playwright-core 1.62 sends (screenSize, isMobile, ...) and rejects unknown
+    // properties, so any fixed viewport fails. viewport:null skips that protocol
+    // call entirely (deviceScaleFactor/isMobile/hasTouch/screen are invalid or
+    // meaningless without a viewport). window.screen is still spoofed via
+    // addInitScript in applyAdvancedStealthConfigurations.
+    if (this._launchedEngine === 'camoufox') {
+      contextOptions.viewport = null;
+      delete contextOptions.deviceScaleFactor;
+      delete contextOptions.isMobile;
+      delete contextOptions.hasTouch;
+      delete contextOptions.screen;
+    }
+
     const context = await this.browser.newContext(contextOptions);
     const contextId = this.generateContextId();
     
@@ -2001,32 +2015,79 @@ export class BrowserEngine {
 export class CamoufoxAdapter extends BrowserEngine {
   name() { return 'camoufox'; }
 
+  /**
+   * Load camoufox through its CJS entry (dist/index.cjs) via createRequire.
+   * The package's ESM entry (dist/index.js, an esbuild bundle) throws
+   * 'Dynamic require of "events" is not supported' when imported from ESM,
+   * so `await import('camoufox')` fails even when the package IS installed.
+   */
+  async _load() {
+    const { createRequire } = await import('module');
+    const require = createRequire(import.meta.url);
+    return require('camoufox'); // CJS build — ESM build is broken
+  }
+
+  /** True only when the camoufox package itself is absent (vs. present but failing to load). */
+  _isNotInstalled(err) {
+    return err?.code === 'MODULE_NOT_FOUND' && (err.message || '').includes("Cannot find module 'camoufox'");
+  }
+
   async isAvailable() {
     try {
-      await import('camoufox');
+      await this._load();
       return true;
-    } catch {
-      return false;
+    } catch (err) {
+      if (this._isNotInstalled(err)) {
+        return false;
+      }
+      // Installed but broken — surface the real error instead of misreporting "not installed".
+      throw new Error(`camoufox is installed but failed to load: ${err.message}`);
     }
   }
 
   async launch(config = {}) {
     let camoufox;
     try {
-      camoufox = await import('camoufox');
-    } catch {
-      throw new Error(
-        'camoufox is not installed. Run: npm install camoufox. Note: camoufox is MIT-licensed and requires Firefox to be installed.'
-      );
+      camoufox = await this._load();
+    } catch (err) {
+      if (this._isNotInstalled(err)) {
+        throw new Error(
+          'camoufox is not installed. Run: npm install camoufox. Note: camoufox is MIT-licensed and requires Firefox to be installed.'
+        );
+      }
+      throw new Error(`camoufox is installed but failed to load: ${err.message}`);
     }
 
-    // camoufox API mirrors playwright — returns a Browser object
-    const browser = await (camoufox.launch || camoufox.default?.launch)({
+    await this._ensureMacOSLayout(camoufox);
+
+    // camoufox's launcher is Camoufox(options) — the package has no launch()
+    // export. It resolves the fetched Firefox binary (npx camoufox fetch) and
+    // returns a Playwright-compatible Browser. Takes `headless` directly plus
+    // passthrough Playwright Firefox launch options.
+    return camoufox.Camoufox({
       headless: config.headless !== false,
       ...config.launchOptions
     });
+  }
 
-    return browser;
+  /**
+   * macOS packaging fix for camoufox-js: it expects properties.json in
+   * Camoufox.app/Contents/MacOS/, but the .app bundle ships it under
+   * Contents/Resources/. Bridge it so the launcher can boot. Best-effort.
+   * (Same fix as ResearchOrchestrator._ensureCamoufoxLayout.)
+   */
+  async _ensureMacOSLayout(camoufox) {
+    if (process.platform !== 'darwin' || !camoufox?.INSTALL_DIR) return;
+    try {
+      const fs = await import('fs');
+      const path = await import('path');
+      const appDir = path.join(camoufox.INSTALL_DIR, 'Camoufox.app', 'Contents');
+      const target = path.join(appDir, 'MacOS', 'properties.json');
+      const source = path.join(appDir, 'Resources', 'properties.json');
+      if (!fs.existsSync(target) && fs.existsSync(source)) {
+        fs.copyFileSync(source, target);
+      }
+    } catch { /* best-effort; launch surfaces a real error if it matters */ }
   }
 }