leapfrog-mcp 0.6.2 → 0.6.3

package/dist/script-executor.d.ts

@@ -0,0 +1,31 @@
+import type { Session } from "./types.js";
+export interface ExecuteOptions {
+    script: string;
+    timeout?: number;
+}
+export interface ExecuteResult {
+    returnValue: string;
+    console: string[];
+    duration: number;
+}
+/**
+ * Sanitize a stack trace to remove:
+ * 1. Server install paths (e.g., /Users/ted/Projects/leapfrog/dist/...)
+ * 2. The async wrapper function frame added by the executor
+ * 3. Adjust line numbers to be relative to the user's script (subtract 1 for wrapper)
+ */
+declare function sanitizeStack(stack: string): string;
+export declare class ScriptExecutor {
+    /**
+     * Whether the execute tool is enabled (LEAP_ALLOW_EXECUTE env var).
+     * Defaults to true when unset.
+     */
+    static isEnabled(): boolean;
+    /**
+     * Execute a user-provided script string in a sandboxed vm context,
+     * with access to the session's Playwright page and browser context.
+     */
+    static execute(session: Session, options: ExecuteOptions): Promise<ExecuteResult>;
+}
+export { sanitizeStack };
+export default ScriptExecutor;

package/dist/script-executor.js

@@ -0,0 +1,249 @@
+// ─── Script Executor ──────────────────────────────────────────────────────
+//
+// Code-first scripting mode: runs Playwright scripts inside a Node.js vm
+// sandbox. Agents send a JS function body string and get back the return
+// value + captured console output.
+//
+// Kill switch: LEAP_ALLOW_EXECUTE (default "true"). Set to "false" to
+// disable entirely.
+import * as vm from "node:vm";
+import { logger } from "./logger.js";
+// ─── Constants ─────────────────────────────────────────────────────────────
+const DEFAULT_TIMEOUT = 60_000;
+const MAX_TIMEOUT = 300_000;
+const BLOCKED_GLOBALS = [
+    "require",
+    "process",
+    "fs",
+    "child_process",
+    "net",
+    "http",
+    "https",
+    "global",
+    "globalThis",
+];
+// ─── Helpers ───────────────────────────────────────────────────────────────
+function clampTimeout(value) {
+    if (value === undefined || value <= 0)
+        return DEFAULT_TIMEOUT;
+    return Math.min(value, MAX_TIMEOUT);
+}
+function createBlockedProxy(name) {
+    // Use a function target so both call-style (require("x")) and
+    // property-access-style (process.pid) throw the correct error.
+    const msg = `Access to '${name}' is not allowed in execute scripts`;
+    const trap = () => {
+        throw new Error(msg);
+    };
+    return new Proxy(trap, {
+        get() {
+            throw new Error(msg);
+        },
+        set() {
+            throw new Error(msg);
+        },
+        apply() {
+            throw new Error(msg);
+        },
+        construct() {
+            throw new Error(msg);
+        },
+    });
+}
+function safeStringify(value) {
+    if (value === undefined) {
+        return "Script completed (no return value)";
+    }
+    try {
+        return JSON.stringify(value);
+    }
+    catch {
+        // Non-serializable (circular refs, functions, etc.)
+        return String(value);
+    }
+}
+// ─── Stack trace sanitization ─────────────────────────────────────────────
+/** Pattern matching file paths that leak server install location */
+const PATH_LEAK_RE = /[A-Za-z]:[\\\/]|\/[Uu]sers\/[^\s:)]+|\/home\/[^\s:)]+|\/tmp\/[^\s:)]+|node_modules\/[^\s:)]+/g;
+/** Pattern matching the async IIFE wrapper frame we inject */
+const WRAPPER_FRAME_RE = /\s*at\s+(async\s+)?execute-script\.js:\d+:\d+\s*$/gm;
+/**
+ * Sanitize a stack trace to remove:
+ * 1. Server install paths (e.g., /Users/ted/Projects/leapfrog/dist/...)
+ * 2. The async wrapper function frame added by the executor
+ * 3. Adjust line numbers to be relative to the user's script (subtract 1 for wrapper)
+ */
+function sanitizeStack(stack) {
+    let sanitized = stack;
+    // Strip file paths that leak server location
+    sanitized = sanitized.replace(PATH_LEAK_RE, "[leapfrog]");
+    // Remove the async IIFE wrapper frames
+    sanitized = sanitized.replace(WRAPPER_FRAME_RE, "");
+    // Adjust line numbers in "execute-script.js:N:M" — subtract 1 for the async wrapper line
+    sanitized = sanitized.replace(/execute-script\.js:(\d+):(\d+)/g, (_match, line, col) => {
+        const adjustedLine = Math.max(1, Number(line) - 1);
+        return `execute-script.js:${adjustedLine}:${col}`;
+    });
+    // Remove empty lines left after stripping
+    sanitized = sanitized
+        .split("\n")
+        .filter((line) => line.trim() !== "")
+        .join("\n");
+    return sanitized;
+}
+// ─── ScriptExecutor ────────────────────────────────────────────────────────
+export class ScriptExecutor {
+    /**
+     * Whether the execute tool is enabled (LEAP_ALLOW_EXECUTE env var).
+     * Defaults to true when unset.
+     */
+    static isEnabled() {
+        const val = process.env.LEAP_ALLOW_EXECUTE;
+        // Only explicitly "false" disables it
+        return val !== "false";
+    }
+    /**
+     * Execute a user-provided script string in a sandboxed vm context,
+     * with access to the session's Playwright page and browser context.
+     */
+    static async execute(session, options) {
+        // ── Kill switch ──────────────────────────────────────────────────
+        if (!ScriptExecutor.isEnabled()) {
+            throw new Error("execute tool is disabled. Set LEAP_ALLOW_EXECUTE=true to enable.");
+        }
+        const timeout = clampTimeout(options.timeout);
+        const consoleOutput = [];
+        const start = Date.now();
+        // ── Console proxy ────────────────────────────────────────────────
+        const consoleProxy = {
+            log: (...args) => {
+                consoleOutput.push(args.map(String).join(" "));
+            },
+            warn: (...args) => {
+                consoleOutput.push(`[WARN] ${args.map(String).join(" ")}`);
+            },
+            error: (...args) => {
+                consoleOutput.push(`[ERROR] ${args.map(String).join(" ")}`);
+            },
+            info: (...args) => {
+                consoleOutput.push(`[INFO] ${args.map(String).join(" ")}`);
+            },
+        };
+        // ── Build sandbox context ────────────────────────────────────────
+        const sandbox = {
+            // Playwright objects
+            page: session.page,
+            context: session.context,
+            // Console proxy
+            console: consoleProxy,
+            // Safe built-ins
+            setTimeout,
+            clearTimeout,
+            Promise,
+            JSON,
+            Array,
+            Object,
+            Map,
+            Set,
+            Date,
+            Math,
+            RegExp,
+            Error,
+            URL,
+            URLSearchParams,
+        };
+        // Wire up blocked globals as throwing proxies
+        for (const name of BLOCKED_GLOBALS) {
+            sandbox[name] = createBlockedProxy(name);
+        }
+        const vmContext = vm.createContext(sandbox);
+        // The vm module sets globalThis to the context object itself, which
+        // overrides our proxy. Re-define it as a throwing getter.
+        // Note: `global` is kept as a proxy in the sandbox (not a vm built-in),
+        // so it doesn't need special handling here.
+        Object.defineProperty(vmContext, "globalThis", {
+            get() {
+                throw new Error("Access to 'globalThis' is not allowed in execute scripts");
+            },
+            configurable: true,
+        });
+        // ── Compile the script ───────────────────────────────────────────
+        // Wrap the user's script in an async IIFE so `await` works at top level.
+        // The user provides the function body, so we wrap it:
+        //   (async () => { <script> })()
+        const wrappedSource = `(async () => {\n${options.script}\n})()`;
+        let compiledScript;
+        try {
+            compiledScript = new vm.Script(wrappedSource, {
+                filename: "execute-script.js",
+            });
+        }
+        catch (err) {
+            const syntaxError = err;
+            logger.warn("script_executor.syntax_error", {
+                message: syntaxError.message,
+            });
+            // Extract line info — subtract 1 for the async wrapper we added
+            const lineMatch = syntaxError.stack?.match(/:(\d+)/);
+            const line = lineMatch ? Math.max(1, Number(lineMatch[1]) - 1) : undefined;
+            const lineInfo = line ? ` (line ${line})` : "";
+            throw new Error(`Script syntax error${lineInfo}: ${syntaxError.message}`);
+        }
+        // ── Execute ──────────────────────────────────────────────────────
+        logger.debug("script_executor.start", { timeout });
+        const ac = new AbortController();
+        const timer = setTimeout(() => ac.abort(), timeout);
+        try {
+            // Run in the vm context. The script returns a Promise (async IIFE).
+            const resultPromise = compiledScript.runInContext(vmContext, {
+                timeout,
+                displayErrors: true,
+            });
+            // Race the promise result against our AbortController timeout
+            const result = await Promise.race([
+                resultPromise,
+                new Promise((_, reject) => {
+                    ac.signal.addEventListener("abort", () => {
+                        reject(new Error(`Script execution timed out after ${timeout}ms`));
+                    });
+                }),
+            ]);
+            const duration = Date.now() - start;
+            logger.debug("script_executor.complete", { duration });
+            return {
+                returnValue: safeStringify(result),
+                console: consoleOutput,
+                duration,
+            };
+        }
+        catch (err) {
+            const duration = Date.now() - start;
+            const error = err;
+            // Check for vm timeout (throws "Script execution timed out")
+            if (error.message?.includes("Script execution timed out") ||
+                error.message?.includes("timed out")) {
+                logger.warn("script_executor.timeout", { timeout, duration });
+                throw new Error(`Script execution timed out after ${timeout}ms`);
+            }
+            // Check for sandbox escape
+            if (error.message?.includes("is not allowed in execute scripts")) {
+                logger.warn("script_executor.blocked_access", {
+                    message: error.message,
+                });
+                throw error;
+            }
+            // Generic runtime error — include sanitized stack context
+            logger.warn("script_executor.runtime_error", {
+                message: error.message,
+            });
+            const rawStack = error.stack ?? "";
+            const stack = sanitizeStack(rawStack);
+            throw new Error(`Script runtime error: ${error.message}\n${stack}`);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}
+export { sanitizeStack };
+export default ScriptExecutor;

package/dist/session-hud.d.ts

@@ -0,0 +1,20 @@
+export type HUDStatus = "active" | "loading" | "waiting" | "error" | "complete";
+/**
+ * Returns the JavaScript string to inject via page.addInitScript().
+ * Creates the ripple container, ripple CSS, and the click ripple function.
+ */
+export declare function getHUDInitScript(sessionName: string): string;
+/** Returns empty string (HUD status bar removed). Kept for API compatibility. */
+export declare function getHUDUpdateScript(_status: HUDStatus, _label?: string): string;
+/** Returns JS for click ripple at coordinates. */
+export declare function getClickRippleScript(x: number, y: number): string;
+/**
+ * Zoom-to-target: two sync scripts with a Playwright waitForTimeout in between.
+ * getScrollToTargetZoomIn zooms the page 2.5x and highlights the element.
+ * getScrollToTargetZoomOut restores normal zoom.
+ * The caller awaits a real delay between them so the human can see.
+ */
+export declare function getScrollToTargetZoomIn(selector: string): string;
+export declare function getScrollToTargetZoomOut(selector: string): string;
+/** Legacy single-call version (sync scroll only, no zoom). */
+export declare function getScrollToTargetScript(selector: string): string;

package/dist/session-hud.js

@@ -0,0 +1,134 @@
+// ─── Session HUD Overlay ──────────────────────────────────────────────────
+//
+// Injects a minimal visual HUD into browser pages: click ripple animation.
+// All functions return JavaScript strings to evaluate in the browser context
+// via page.addInitScript() or page.evaluate().
+//
+// Opt-in via LEAP_HUD=true env var (caller checks, not this module).
+//
+// Integration point: import { getHUDInitScript, ... } from "./session-hud.js"
+//
+import { logger } from "./logger.js";
+// ─── Init Script ───────────────────────────────────────────────────────────
+/**
+ * Returns the JavaScript string to inject via page.addInitScript().
+ * Creates the ripple container, ripple CSS, and the click ripple function.
+ */
+export function getHUDInitScript(sessionName) {
+    logger.debug(`Generating HUD init script for session: ${sessionName}`);
+    return `(function() {
+  if (window.__leapfrog_hud_initialized) return;
+  window.__leapfrog_hud_initialized = true;
+
+  // ── CSS (ripple only) ────────────────────────────────────────────────
+  var style = document.createElement('style');
+  style.setAttribute('data-leapfrog', 'true');
+  style.textContent = \`
+    #leapfrog-ripple-container {
+      position: fixed;
+      top: 0;
+      left: 0;
+      width: 100%;
+      height: 100%;
+      z-index: 2147483646;
+      pointer-events: none;
+      overflow: hidden;
+    }
+
+    @keyframes leapfrog-ripple {
+      0% {
+        width: 20px;
+        height: 20px;
+        opacity: 0.6;
+      }
+      100% {
+        width: 80px;
+        height: 80px;
+        opacity: 0;
+      }
+    }
+
+    .leapfrog-ripple {
+      position: absolute;
+      border-radius: 50%;
+      background: rgba(34, 197, 94, 0.4);
+      animation: leapfrog-ripple 0.6s ease-out forwards;
+      pointer-events: none;
+      transform: translate(-50%, -50%);
+    }
+  \`;
+  document.head.appendChild(style);
+
+  document.documentElement.setAttribute('data-leapfrog', 'true');
+
+  // ── Ripple Container ─────────────────────────────────────────────────
+  var rippleContainer = document.createElement('div');
+  rippleContainer.id = 'leapfrog-ripple-container';
+  rippleContainer.setAttribute('data-leapfrog', 'true');
+  document.body.appendChild(rippleContainer);
+
+  // ── Control Functions ────────────────────────────────────────────────
+  window.__leapfrog_clickRipple = function(x, y) {
+    var container = document.getElementById('leapfrog-ripple-container');
+    if (!container) return;
+    var ripple = document.createElement('div');
+    ripple.className = 'leapfrog-ripple';
+    ripple.setAttribute('data-leapfrog', 'true');
+    ripple.style.left = x + 'px';
+    ripple.style.top = y + 'px';
+    container.appendChild(ripple);
+    ripple.addEventListener('animationend', function() { ripple.remove(); });
+  };
+})();`;
+}
+// ─── Live Update Scripts ───────────────────────────────────────────────────
+/** Returns empty string (HUD status bar removed). Kept for API compatibility. */
+export function getHUDUpdateScript(_status, _label) {
+    return "";
+}
+/** Returns JS for click ripple at coordinates. */
+export function getClickRippleScript(x, y) {
+    return `window.__leapfrog_clickRipple && window.__leapfrog_clickRipple(${x}, ${y});`;
+}
+// ─── Scroll-to-Target ─────────────────────────────────────────────────────
+/**
+ * Zoom-to-target: two sync scripts with a Playwright waitForTimeout in between.
+ * getScrollToTargetZoomIn zooms the page 2.5x and highlights the element.
+ * getScrollToTargetZoomOut restores normal zoom.
+ * The caller awaits a real delay between them so the human can see.
+ */
+export function getScrollToTargetZoomIn(selector) {
+    const escaped = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+    return `(function() {
+  var el = document.querySelector('${escaped}');
+  if (!el) return false;
+  el.scrollIntoView({ block: 'center' });
+  document.body.style.zoom = '2.5';
+  el.scrollIntoView({ block: 'center' });
+  el.style.outline = '3px solid #22c55e';
+  el.style.outlineOffset = '4px';
+  el.style.backgroundColor = 'rgba(34, 197, 94, 0.1)';
+  return true;
+})()`;
+}
+export function getScrollToTargetZoomOut(selector) {
+    const escaped = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+    return `(function() {
+  var el = document.querySelector('${escaped}');
+  document.body.style.zoom = '1';
+  if (el) {
+    el.style.outline = '';
+    el.style.outlineOffset = '';
+    el.style.backgroundColor = '';
+    el.scrollIntoView({ block: 'center' });
+  }
+})()`;
+}
+/** Legacy single-call version (sync scroll only, no zoom). */
+export function getScrollToTargetScript(selector) {
+    const escaped = selector.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+    return `(function() {
+  var el = document.querySelector('${escaped}');
+  if (el) el.scrollIntoView({ behavior: 'smooth', block: 'center' });
+})()`;
+}

package/dist/snapshot-differ.d.ts

@@ -0,0 +1,26 @@
+import type { SnapshotResult } from "./types.js";
+export interface SnapshotDiff {
+    /** Number of changes detected */
+    changeCount: number;
+    /** Human-readable diff text */
+    diffText: string;
+    /** Whether this is the first snapshot (no diff available) */
+    isFirst: boolean;
+    /** Token estimate for the diff vs full snapshot */
+    diffTokenEstimate: number;
+    fullTokenEstimate: number;
+}
+export declare class SnapshotDiffer {
+    /** Compare current snapshot with cached version, update cache */
+    static diff(sessionId: string, pageUrl: string, current: SnapshotResult): SnapshotDiff;
+    /** Clear cached snapshots for a session */
+    static clearSession(sessionId: string): void;
+    /** Clear all cached snapshots */
+    static clearAll(): void;
+    /** Get cache stats */
+    static stats(): {
+        size: number;
+        maxSize: number;
+    };
+}
+export default SnapshotDiffer;

package/dist/snapshot-differ.js

@@ -0,0 +1,225 @@
+import { logger } from "./logger.js";
+// ─── Constants ────────────────────────────────────────────────────────────
+const MAX_CACHE_SIZE = 100;
+const REF_LINE_RE = /^(\s*)(@e\d+)\s+(.*)$/;
+// ─── Internal cache ───────────────────────────────────────────────────────
+const cache = new Map();
+function cacheKey(sessionId, pageUrl) {
+    return `${sessionId}:${pageUrl}`;
+}
+function evictLRU() {
+    if (cache.size < MAX_CACHE_SIZE)
+        return;
+    let oldestKey = "";
+    let oldestTime = Infinity;
+    for (const [key, entry] of cache) {
+        if (entry.accessedAt < oldestTime) {
+            oldestTime = entry.accessedAt;
+            oldestKey = key;
+        }
+    }
+    if (oldestKey) {
+        cache.delete(oldestKey);
+        logger.debug("snapshot_differ_evict", { key: oldestKey });
+    }
+}
+/** Extract type and accessible name from the content portion after the ref */
+function parseContent(content) {
+    // content looks like: 'link "Home"' or 'main' or 'navigation "Main Nav"'
+    const nameMatch = content.match(/^(\S+)\s+"(.*)"$/);
+    if (nameMatch) {
+        return { type: nameMatch[1].toLowerCase(), name: nameMatch[2].toLowerCase().trim() };
+    }
+    // No quoted name — just a type like "main"
+    const typeOnly = content.trim().split(/\s+/)[0];
+    return { type: (typeOnly || "unknown").toLowerCase(), name: "" };
+}
+/**
+ * Build a fingerprint map from snapshot text.
+ * Fingerprint = `${type}:${name}` for named elements, `${type}:${lineIndex}` for unnamed.
+ * Duplicates are disambiguated with `_N` suffix.
+ */
+function parseFingerprintMap(text) {
+    const lines = text.split("\n");
+    const elements = [];
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        const m = line.match(REF_LINE_RE);
+        if (m) {
+            const ref = m[2];
+            const desc = m[3];
+            const { type, name } = parseContent(desc);
+            elements.push({ ref, type, name, fullLine: line, desc });
+        }
+    }
+    // Build raw fingerprints — type:name for named, type: for unnamed
+    // Duplicates (both named and unnamed) are disambiguated below with _N suffix
+    const rawFingerprints = elements.map((el) => {
+        if (el.name) {
+            return `${el.type}:${el.name}`;
+        }
+        return `${el.type}:`;
+    });
+    // Count occurrences of each fingerprint to find duplicates
+    const countMap = new Map();
+    for (const fp of rawFingerprints) {
+        countMap.set(fp, (countMap.get(fp) || 0) + 1);
+    }
+    // Assign final fingerprints with _N suffix for duplicates
+    const occurrenceTracker = new Map();
+    const result = new Map();
+    for (let i = 0; i < elements.length; i++) {
+        let fp = rawFingerprints[i];
+        const count = countMap.get(fp) || 1;
+        if (count > 1) {
+            const occurrence = occurrenceTracker.get(fp) || 0;
+            occurrenceTracker.set(fp, occurrence + 1);
+            fp = `${fp}_${occurrence}`;
+        }
+        result.set(fp, elements[i]);
+    }
+    return result;
+}
+/** Estimate tokens from character count (chars / 4) */
+function estimateTokens(text) {
+    return Math.ceil(text.length / 4);
+}
+// ─── Differ ───────────────────────────────────────────────────────────────
+export class SnapshotDiffer {
+    /** Compare current snapshot with cached version, update cache */
+    static diff(sessionId, pageUrl, current) {
+        const key = cacheKey(sessionId, pageUrl);
+        const prev = cache.get(key);
+        const fullTokenEstimate = estimateTokens(current.text);
+        // Store / update cache (only evict if this is a genuinely new key)
+        if (!cache.has(key))
+            evictLRU();
+        cache.set(key, { text: current.text, accessedAt: Date.now() });
+        // First snapshot — no previous to compare against
+        if (!prev) {
+            logger.debug("snapshot_differ_first", { sessionId, pageUrl });
+            return {
+                changeCount: 0,
+                diffText: "",
+                isFirst: true,
+                diffTokenEstimate: 0,
+                fullTokenEstimate,
+            };
+        }
+        // Parse both snapshots into fingerprint -> element maps
+        const oldMap = parseFingerprintMap(prev.text);
+        const newMap = parseFingerprintMap(current.text);
+        const added = [];
+        const removed = [];
+        const changed = [];
+        // Track which fingerprints have been matched
+        const matchedOld = new Set();
+        const matchedNew = new Set();
+        // Pass 1: Exact fingerprint matches (same type + same name)
+        for (const [fp, newEl] of newMap) {
+            const oldEl = oldMap.get(fp);
+            if (oldEl !== undefined) {
+                matchedOld.add(fp);
+                matchedNew.add(fp);
+                // Same identity — check for structural/content changes (ignoring ref ID shifts)
+                const oldStripped = oldEl.fullLine.replace(/@e\d+/, "");
+                const newStripped = newEl.fullLine.replace(/@e\d+/, "");
+                if (oldStripped !== newStripped) {
+                    changed.push(`~ ${newEl.ref} ${oldEl.desc} → ${newEl.desc} (changed)`);
+                }
+            }
+        }
+        // Pass 2: Pair unmatched elements of the same type as "changed"
+        // (handles cases like heading text changing from "Welcome" to "New Title")
+        const unmatchedOld = new Map();
+        for (const [fp, el] of oldMap) {
+            if (!matchedOld.has(fp)) {
+                const list = unmatchedOld.get(el.type) || [];
+                list.push({ fp, el });
+                unmatchedOld.set(el.type, list);
+            }
+        }
+        const unmatchedNew = new Map();
+        for (const [fp, el] of newMap) {
+            if (!matchedNew.has(fp)) {
+                const list = unmatchedNew.get(el.type) || [];
+                list.push({ fp, el });
+                unmatchedNew.set(el.type, list);
+            }
+        }
+        // Pair unmatched elements of the same type (in order) as changes
+        for (const [type, oldList] of unmatchedOld) {
+            const newList = unmatchedNew.get(type) || [];
+            const pairCount = Math.min(oldList.length, newList.length);
+            for (let i = 0; i < pairCount; i++) {
+                const oldEl = oldList[i].el;
+                const newEl = newList[i].el;
+                matchedOld.add(oldList[i].fp);
+                matchedNew.add(newList[i].fp);
+                changed.push(`~ ${newEl.ref} ${oldEl.desc} → ${newEl.desc} (changed)`);
+            }
+        }
+        // Remaining unmatched = pure adds / removes
+        for (const [fp, newEl] of newMap) {
+            if (!matchedNew.has(fp)) {
+                added.push(`+ ${newEl.ref} ${newEl.desc} (new)`);
+            }
+        }
+        for (const [fp, oldEl] of oldMap) {
+            if (!matchedOld.has(fp)) {
+                removed.push(`- ${oldEl.ref} ${oldEl.desc} (removed)`);
+            }
+        }
+        const changeCount = added.length + removed.length + changed.length;
+        if (changeCount === 0) {
+            return {
+                changeCount: 0,
+                diffText: "[INCREMENTAL SNAPSHOT — 0 changes since last snapshot]",
+                isFirst: false,
+                diffTokenEstimate: estimateTokens("[INCREMENTAL SNAPSHOT — 0 changes since last snapshot]"),
+                fullTokenEstimate,
+            };
+        }
+        const lines = [
+            `[INCREMENTAL SNAPSHOT — ${changeCount} change${changeCount === 1 ? "" : "s"} since last snapshot]`,
+            ...added,
+            ...changed,
+            ...removed,
+        ];
+        const diffText = lines.join("\n");
+        logger.debug("snapshot_differ_diff", {
+            sessionId,
+            pageUrl,
+            added: added.length,
+            changed: changed.length,
+            removed: removed.length,
+        });
+        return {
+            changeCount,
+            diffText,
+            isFirst: false,
+            diffTokenEstimate: estimateTokens(diffText),
+            fullTokenEstimate,
+        };
+    }
+    /** Clear cached snapshots for a session */
+    static clearSession(sessionId) {
+        const prefix = `${sessionId}:`;
+        for (const key of cache.keys()) {
+            if (key.startsWith(prefix)) {
+                cache.delete(key);
+            }
+        }
+        logger.debug("snapshot_differ_clear_session", { sessionId });
+    }
+    /** Clear all cached snapshots */
+    static clearAll() {
+        cache.clear();
+        logger.debug("snapshot_differ_clear_all");
+    }
+    /** Get cache stats */
+    static stats() {
+        return { size: cache.size, maxSize: MAX_CACHE_SIZE };
+    }
+}
+export default SnapshotDiffer;