@predicatelabs/sdk 0.99.9

package/dist/runtime-agent.js

@@ -0,0 +1,357 @@
+"use strict";
+/**
+ * AgentRuntime-backed agent with optional vision executor fallback.
+ *
+ * This keeps the control plane verification-first:
+ * - Actions may be proposed by either a structured executor (DOM snapshot prompt)
+ *   or a vision executor (screenshot prompt).
+ * - Verification is always executed via AgentRuntime predicates.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RuntimeAgent = void 0;
+const llm_interaction_handler_1 = require("./utils/llm-interaction-handler");
+class RuntimeAgent {
+    constructor(opts) {
+        this.runtime = opts.runtime;
+        this.executor = opts.executor;
+        this.visionExecutor = opts.visionExecutor;
+        this.visionVerifier = opts.visionVerifier;
+        this.shortCircuitCanvas = opts.shortCircuitCanvas ?? true;
+        this.structuredLLM = new llm_interaction_handler_1.LLMInteractionHandler(this.executor, false);
+    }
+    async runStep(opts) {
+        const { taskGoal, step, onStepStart, onStepEnd } = opts;
+        const stepId = this.runtime.beginStep(step.goal);
+        await this.runHook(onStepStart, {
+            stepId,
+            stepIndex: this.runtime.stepIndex,
+            goal: step.goal,
+            attempt: 0,
+            url: this.runtime.lastSnapshot?.url ?? this.runtime.page?.url?.() ?? null,
+        });
+        let ok = false;
+        let emitted = false;
+        let outcome = null;
+        let errorMessage = null;
+        try {
+            const snap = await this.snapshotWithRamp(step);
+            if (await this.shouldShortCircuitToVision(step, snap)) {
+                ok = await this.visionExecutorAttempt({ taskGoal, step, snap });
+                outcome = ok ? 'ok' : 'verification_failed';
+                return ok;
+            }
+            // 1) Structured executor attempt.
+            const action = await this.proposeStructuredAction({ taskGoal, step, snap });
+            await this.executeAction(action, snap);
+            ok = await this.applyVerifications(step);
+            if (ok) {
+                outcome = 'ok';
+                return true;
+            }
+            // 2) Optional vision executor fallback (bounded).
+            const enabled = step.visionExecutorEnabled ?? true;
+            const maxAttempts = step.maxVisionExecutorAttempts ?? 1;
+            if (enabled && maxAttempts > 0) {
+                ok = await this.visionExecutorAttempt({ taskGoal, step, snap });
+                outcome = ok ? 'ok' : 'verification_failed';
+                return ok;
+            }
+            outcome = 'verification_failed';
+            return false;
+        }
+        catch (error) {
+            errorMessage = String(error?.message ?? error);
+            outcome = 'exception';
+            this.runtime.emitStepEnd({
+                success: false,
+                verifyPassed: false,
+                error: errorMessage,
+                outcome: 'exception',
+            });
+            emitted = true;
+            throw error;
+        }
+        finally {
+            if (!emitted) {
+                this.runtime.emitStepEnd({
+                    success: ok,
+                    verifyPassed: ok,
+                    outcome: ok ? 'ok' : 'verification_failed',
+                });
+            }
+            await this.runHook(onStepEnd, {
+                stepId,
+                stepIndex: this.runtime.stepIndex,
+                goal: step.goal,
+                attempt: 0,
+                url: this.runtime.lastSnapshot?.url ?? this.runtime.page?.url?.() ?? null,
+                success: ok,
+                outcome,
+                error: errorMessage,
+            });
+        }
+    }
+    async runHook(hook, ctx) {
+        if (!hook)
+            return;
+        try {
+            await Promise.resolve(hook(ctx));
+        }
+        catch {
+            // best-effort hook; ignore errors
+        }
+    }
+    async snapshotWithRamp(step) {
+        const base = step.snapshotLimitBase ?? 60;
+        const stepInc = step.snapshotLimitStep ?? 40;
+        const max = step.snapshotLimitMax ?? 220;
+        const attempts = Math.max(1, step.maxSnapshotAttempts ?? 3);
+        const minConf = step.minConfidence;
+        const minActionables = step.minActionables;
+        let limit = base;
+        let last = null;
+        for (let i = 0; i < attempts; i++) {
+            last = await this.runtime.snapshot({ limit, goal: step.goal });
+            if (typeof minConf === 'number') {
+                const conf = last?.diagnostics?.confidence;
+                if (typeof conf === 'number' && Number.isFinite(conf) && conf < minConf) {
+                    limit = Math.min(max, limit + stepInc);
+                    continue;
+                }
+            }
+            if (typeof minActionables === 'number') {
+                if (this.countActionables(last) < minActionables) {
+                    limit = Math.min(max, limit + stepInc);
+                    continue;
+                }
+            }
+            return last;
+        }
+        if (!last)
+            throw new Error('snapshot() returned null/undefined repeatedly');
+        return last;
+    }
+    async proposeStructuredAction(opts) {
+        const { taskGoal, step, snap } = opts;
+        const domContext = this.structuredLLM.buildContext(snap, step.goal);
+        const combinedGoal = `${taskGoal}\n\nSTEP: ${step.goal}`;
+        const resp = await this.structuredLLM.queryLLM(domContext, combinedGoal);
+        return this.extractActionFromText(resp.content);
+    }
+    async visionExecutorAttempt(opts) {
+        const { taskGoal, step, snap } = opts;
+        const provider = this.visionExecutor;
+        if (!provider || !provider.supportsVision?.())
+            return false;
+        const url = this.runtime.page?.url?.() ?? snap?.url ?? '(unknown)';
+        const buf = (await this.runtime.page.screenshot({ type: 'png' }));
+        const imageBase64 = Buffer.from(buf).toString('base64');
+        const { systemPrompt, userPrompt } = this.visionExecutorPrompts({
+            taskGoal,
+            step,
+            url,
+            snap,
+        });
+        const resp = await provider.generateWithImage(systemPrompt, userPrompt, imageBase64, {
+            temperature: 0.0,
+        });
+        const action = this.extractActionFromText(resp.content);
+        await this.executeAction(action, snap ?? undefined);
+        // This is a retry of the same step; clear prior step assertions.
+        this.runtime.flushAssertions();
+        return await this.applyVerifications(step);
+    }
+    async applyVerifications(step) {
+        const verifications = step.verifications ?? [];
+        if (verifications.length === 0)
+            return true;
+        let allOk = true;
+        for (const v of verifications) {
+            const required = v.required ?? true;
+            const eventually = v.eventually ?? true;
+            let ok;
+            if (eventually) {
+                ok = await this.runtime.check(v.predicate, v.label, required).eventually({
+                    timeoutMs: v.timeoutMs ?? 10000,
+                    pollMs: v.pollMs ?? 250,
+                    minConfidence: v.minConfidence,
+                    maxSnapshotAttempts: v.maxSnapshotAttempts,
+                    visionProvider: this.visionVerifier,
+                });
+            }
+            else {
+                ok = this.runtime.assert(v.predicate, v.label, required);
+            }
+            allOk = allOk && ok;
+        }
+        return this.runtime.requiredAssertionsPassed() && allOk;
+    }
+    async executeAction(action, snap) {
+        const url = this.runtime.page?.url?.() ?? snap?.url;
+        await this.runtime.recordAction(action, url);
+        const parsed = this.parseAction(action);
+        if (parsed.kind === 'finish')
+            return;
+        if (parsed.kind === 'press') {
+            await this.runtime.page.keyboard.press(parsed.key);
+            await this.stabilizeBestEffort();
+            return;
+        }
+        if (parsed.kind === 'click_xy') {
+            await this.runtime.page.mouse.click(parsed.x, parsed.y);
+            await this.stabilizeBestEffort();
+            return;
+        }
+        if (parsed.kind === 'click_rect') {
+            const x = parsed.x + parsed.w / 2;
+            const y = parsed.y + parsed.h / 2;
+            await this.runtime.page.mouse.click(x, y);
+            await this.stabilizeBestEffort();
+            return;
+        }
+        if (!snap)
+            throw new Error('Cannot execute CLICK(id)/TYPE(id, ...) without a snapshot');
+        if (parsed.kind === 'click_id') {
+            const el = this.findElement(snap, parsed.id);
+            if (!el)
+                throw new Error(`Element id ${parsed.id} not found in snapshot`);
+            await this.clickBBox(el.bbox);
+            await this.stabilizeBestEffort();
+            return;
+        }
+        if (parsed.kind === 'type_id') {
+            const el = this.findElement(snap, parsed.id);
+            if (!el)
+                throw new Error(`Element id ${parsed.id} not found in snapshot`);
+            await this.clickBBox(el.bbox);
+            await this.runtime.page.keyboard.type(parsed.text);
+            await this.stabilizeBestEffort();
+            return;
+        }
+    }
+    async stabilizeBestEffort() {
+        try {
+            await this.runtime.page.waitForTimeout(50);
+        }
+        catch {
+            // best-effort
+        }
+    }
+    clickBBox(bbox) {
+        const x = bbox.x + bbox.width / 2;
+        const y = bbox.y + bbox.height / 2;
+        return this.runtime.page.mouse.click(x, y);
+    }
+    findElement(snap, id) {
+        return snap.elements.find(e => e.id === id);
+    }
+    countActionables(snap) {
+        let n = 0;
+        for (const el of snap.elements ?? []) {
+            if (el.visual_cues?.is_clickable)
+                n += 1;
+        }
+        return n;
+    }
+    async shouldShortCircuitToVision(step, snap) {
+        const enabled = step.visionExecutorEnabled ?? true;
+        if (!enabled)
+            return false;
+        if (!this.visionExecutor || !this.visionExecutor.supportsVision?.())
+            return false;
+        if (!snap)
+            return true;
+        const minActionables = step.minActionables;
+        if (typeof minActionables === 'number' && this.countActionables(snap) < minActionables) {
+            if (this.shortCircuitCanvas) {
+                try {
+                    const n = await this.runtime.page.evaluate("document.querySelectorAll('canvas').length");
+                    if (typeof n === 'number' && n > 0)
+                        return true;
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+        return false;
+    }
+    visionExecutorPrompts(opts) {
+        const verifyTargets = this.verificationTargetsHuman(opts.step.verifications ?? []);
+        const snapshotSummary = opts.snap
+            ? `\n\nStructured snapshot summary:\n- url: ${opts.snap.url}\n- elements: ${opts.snap.elements?.length ?? 0}\n`
+            : '';
+        const systemPrompt = `You are a vision-capable web automation executor.
+
+TASK GOAL:
+${opts.taskGoal}
+
+STEP GOAL:
+${opts.step.goal}
+
+CURRENT URL (text):
+${opts.url || '(unknown)'}
+
+VERIFICATION TARGETS (text):
+${verifyTargets || '(none provided)'}${snapshotSummary}
+
+RESPONSE FORMAT:
+Return ONLY ONE of:
+- CLICK(id)
+- TYPE(id, "text")
+- CLICK_XY(x, y)
+- CLICK_RECT(x, y, w, h)
+- PRESS("key")
+- FINISH()
+
+No explanations, no markdown.
+`;
+        return {
+            systemPrompt,
+            userPrompt: 'From the screenshot, return the single best next action:',
+        };
+    }
+    verificationTargetsHuman(verifications) {
+        if (!verifications.length)
+            return '';
+        return verifications
+            .map(v => `- ${v.label} (${(v.required ?? true) ? 'required' : 'optional'})`)
+            .join('\n');
+    }
+    parseAction(action) {
+        const s = action.trim();
+        if (/^FINISH\s*\(\s*\)\s*$/i.test(s))
+            return { kind: 'finish' };
+        const mXY = s.match(/^CLICK_XY\s*\(\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*\)\s*$/i);
+        if (mXY)
+            return { kind: 'click_xy', x: Number(mXY[1]), y: Number(mXY[2]) };
+        const mRect = s.match(/^CLICK_RECT\s*\(\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*,\s*(-?\d+(?:\.\d+)?)\s*\)\s*$/i);
+        if (mRect) {
+            return {
+                kind: 'click_rect',
+                x: Number(mRect[1]),
+                y: Number(mRect[2]),
+                w: Number(mRect[3]),
+                h: Number(mRect[4]),
+            };
+        }
+        const mClick = s.match(/^CLICK\s*\(\s*(\d+)\s*\)\s*$/i);
+        if (mClick)
+            return { kind: 'click_id', id: Number(mClick[1]) };
+        const mType = s.match(/^TYPE\s*\(\s*(\d+)\s*,\s*["']([^"']*)["']\s*\)\s*$/i);
+        if (mType)
+            return { kind: 'type_id', id: Number(mType[1]), text: mType[2] };
+        const mPress = s.match(/^PRESS\s*\(\s*["']([^"']+)["']\s*\)\s*$/i);
+        if (mPress)
+            return { kind: 'press', key: mPress[1] };
+        throw new Error(`Unknown action format: ${action}`);
+    }
+    extractActionFromText(text) {
+        const cleaned = (text || '').replace(/```[\w]*\n?/g, '').trim();
+        const pat = /(CLICK_XY\s*\(\s*-?\d+(?:\.\d+)?\s*,\s*-?\d+(?:\.\d+)?\s*\)|CLICK_RECT\s*\(\s*-?\d+(?:\.\d+)?\s*,\s*-?\d+(?:\.\d+)?\s*,\s*-?\d+(?:\.\d+)?\s*,\s*-?\d+(?:\.\d+)?\s*\)|CLICK\s*\(\s*\d+\s*\)|TYPE\s*\(\s*\d+\s*,\s*["'].*?["']\s*\)|PRESS\s*\(\s*["'].*?["']\s*\)|FINISH\s*\(\s*\))/i;
+        const m = cleaned.match(pat);
+        return m ? m[1] : cleaned;
+    }
+}
+exports.RuntimeAgent = RuntimeAgent;
+//# sourceMappingURL=runtime-agent.js.map

package/dist/runtime-agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-agent.js","sourceRoot":"","sources":["../src/runtime-agent.ts"],"names":[],"mappings":"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"}

package/dist/screenshot.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Screenshot functionality - standalone screenshot capture
+ */
+import { SentienceBrowser } from './browser';
+export interface ScreenshotOptions {
+    format?: 'png' | 'jpeg';
+    quality?: number;
+}
+/**
+ * Capture screenshot of current page
+ *
+ * @param browser - SentienceBrowser instance
+ * @param options - Screenshot options
+ * @returns Base64-encoded screenshot data URL (e.g., "data:image/png;base64,...")
+ */
+export declare function screenshot(browser: SentienceBrowser, options?: ScreenshotOptions): Promise<string>;
+//# sourceMappingURL=screenshot.d.ts.map

package/dist/screenshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot.d.ts","sourceRoot":"","sources":["../src/screenshot.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,gBAAgB,EAAE,MAAM,WAAW,CAAC;AAE7C,MAAM,WAAW,iBAAiB;IAChC,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,CAAC;IACxB,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,gBAAgB,EACzB,OAAO,GAAE,iBAAsB,GAC9B,OAAO,CAAC,MAAM,CAAC,CA8BjB"}

package/dist/screenshot.js

@@ -0,0 +1,40 @@
+"use strict";
+/**
+ * Screenshot functionality - standalone screenshot capture
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.screenshot = screenshot;
+/**
+ * Capture screenshot of current page
+ *
+ * @param browser - SentienceBrowser instance
+ * @param options - Screenshot options
+ * @returns Base64-encoded screenshot data URL (e.g., "data:image/png;base64,...")
+ */
+async function screenshot(browser, options = {}) {
+    const page = browser.getPage();
+    if (!page) {
+        throw new Error('Browser not started. Call start() first.');
+    }
+    const format = options.format || 'png';
+    const quality = options.quality;
+    if (format === 'jpeg' && quality !== undefined) {
+        if (quality < 1 || quality > 100) {
+            throw new Error('Quality must be between 1 and 100 for JPEG format');
+        }
+    }
+    // Use Playwright's screenshot with base64 encoding
+    const screenshotOptions = {
+        type: format,
+        encoding: 'base64',
+    };
+    if (format === 'jpeg' && quality !== undefined) {
+        screenshotOptions.quality = quality;
+    }
+    // Capture screenshot
+    const base64Data = await page.screenshot(screenshotOptions);
+    // Return as data URL
+    const mimeType = format === 'png' ? 'image/png' : 'image/jpeg';
+    return `data:${mimeType};base64,${base64Data}`;
+}
+//# sourceMappingURL=screenshot.js.map

package/dist/screenshot.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"screenshot.js","sourceRoot":"","sources":["../src/screenshot.ts"],"names":[],"mappings":";AAAA;;GAEG;;AAgBH,gCAiCC;AAxCD;;;;;;GAMG;AACI,KAAK,UAAU,UAAU,CAC9B,OAAyB,EACzB,UAA6B,EAAE;IAE/B,MAAM,IAAI,GAAG,OAAO,CAAC,OAAO,EAAE,CAAC;IAC/B,IAAI,CAAC,IAAI,EAAE,CAAC;QACV,MAAM,IAAI,KAAK,CAAC,0CAA0C,CAAC,CAAC;IAC9D,CAAC;IACD,MAAM,MAAM,GAAG,OAAO,CAAC,MAAM,IAAI,KAAK,CAAC;IACvC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,CAAC;IAEhC,IAAI,MAAM,KAAK,MAAM,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC/C,IAAI,OAAO,GAAG,CAAC,IAAI,OAAO,GAAG,GAAG,EAAE,CAAC;YACjC,MAAM,IAAI,KAAK,CAAC,mDAAmD,CAAC,CAAC;QACvE,CAAC;IACH,CAAC;IAED,mDAAmD;IACnD,MAAM,iBAAiB,GAAQ;QAC7B,IAAI,EAAE,MAAM;QACZ,QAAQ,EAAE,QAAQ;KACnB,CAAC;IAEF,IAAI,MAAM,KAAK,MAAM,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC;QAC/C,iBAAiB,CAAC,OAAO,GAAG,OAAO,CAAC;IACtC,CAAC;IAED,qBAAqB;IACrB,MAAM,UAAU,GAAG,MAAM,IAAI,CAAC,UAAU,CAAC,iBAAiB,CAAC,CAAC;IAE5D,qBAAqB;IACrB,MAAM,QAAQ,GAAG,MAAM,KAAK,KAAK,CAAC,CAAC,CAAC,WAAW,CAAC,CAAC,CAAC,YAAY,CAAC;IAC/D,OAAO,QAAQ,QAAQ,WAAW,UAAU,EAAE,CAAC;AACjD,CAAC"}

package/dist/snapshot-diff.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Snapshot comparison utilities for diff_status detection.
+ * Implements change detection logic for the Diff Overlay feature.
+ *
+ * Uses shared canonicalization helpers from canonicalization.ts to ensure
+ * consistent comparison behavior with tracing/indexer.ts.
+ */
+import { Element, Snapshot } from './types';
+export declare class SnapshotDiff {
+    /**
+     * Compare current snapshot with previous and set diff_status on elements.
+     *
+     * Uses canonicalized comparisons:
+     * - Text is normalized (trimmed, collapsed whitespace, lowercased)
+     * - Bbox is rounded to 2px grid to ignore sub-pixel differences
+     *
+     * @param current - Current snapshot
+     * @param previous - Previous snapshot (undefined if this is the first snapshot)
+     * @returns List of elements with diff_status set (includes REMOVED elements from previous)
+     */
+    static computeDiffStatus(current: Snapshot, previous: Snapshot | undefined): Element[];
+}
+//# sourceMappingURL=snapshot-diff.d.ts.map

package/dist/snapshot-diff.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-diff.d.ts","sourceRoot":"","sources":["../src/snapshot-diff.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,OAAO,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAuB5C,qBAAa,YAAY;IACvB;;;;;;;;;;OAUG;IACH,MAAM,CAAC,iBAAiB,CAAC,OAAO,EAAE,QAAQ,EAAE,QAAQ,EAAE,QAAQ,GAAG,SAAS,GAAG,OAAO,EAAE;CA8EvF"}

package/dist/snapshot-diff.js

@@ -0,0 +1,119 @@
+"use strict";
+/**
+ * Snapshot comparison utilities for diff_status detection.
+ * Implements change detection logic for the Diff Overlay feature.
+ *
+ * Uses shared canonicalization helpers from canonicalization.ts to ensure
+ * consistent comparison behavior with tracing/indexer.ts.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SnapshotDiff = void 0;
+const canonicalization_1 = require("./canonicalization");
+/**
+ * Convert Element to ElementData for canonicalization helpers.
+ */
+function elementToData(el) {
+    return {
+        id: el.id,
+        role: el.role,
+        text: el.text,
+        bbox: {
+            x: el.bbox.x,
+            y: el.bbox.y,
+            width: el.bbox.width,
+            height: el.bbox.height,
+        },
+        visual_cues: {
+            is_primary: el.visual_cues.is_primary,
+            is_clickable: el.visual_cues.is_clickable,
+        },
+    };
+}
+class SnapshotDiff {
+    /**
+     * Compare current snapshot with previous and set diff_status on elements.
+     *
+     * Uses canonicalized comparisons:
+     * - Text is normalized (trimmed, collapsed whitespace, lowercased)
+     * - Bbox is rounded to 2px grid to ignore sub-pixel differences
+     *
+     * @param current - Current snapshot
+     * @param previous - Previous snapshot (undefined if this is the first snapshot)
+     * @returns List of elements with diff_status set (includes REMOVED elements from previous)
+     */
+    static computeDiffStatus(current, previous) {
+        // If no previous snapshot, all current elements are ADDED
+        if (!previous) {
+            return current.elements.map(el => ({
+                ...el,
+                diff_status: 'ADDED',
+            }));
+        }
+        // Build lookup maps by element ID
+        const currentById = new Map(current.elements.map(el => [el.id, el]));
+        const previousById = new Map(previous.elements.map(el => [el.id, el]));
+        const currentIds = new Set(currentById.keys());
+        const previousIds = new Set(previousById.keys());
+        const result = [];
+        // Process current elements
+        for (const el of current.elements) {
+            if (!previousIds.has(el.id)) {
+                // Element is new - mark as ADDED
+                result.push({
+                    ...el,
+                    diff_status: 'ADDED',
+                });
+            }
+            else {
+                // Element existed before - check for changes using canonicalized comparisons
+                const prevEl = previousById.get(el.id);
+                // Convert to ElementData for canonicalization helpers
+                const elData = elementToData(el);
+                const prevElData = elementToData(prevEl);
+                const hasBboxChanged = (0, canonicalization_1.bboxChanged)(elData.bbox, prevElData.bbox);
+                const hasContentChanged = (0, canonicalization_1.contentChanged)(elData, prevElData);
+                if (hasBboxChanged && hasContentChanged) {
+                    // Both position and content changed - mark as MODIFIED
+                    result.push({
+                        ...el,
+                        diff_status: 'MODIFIED',
+                    });
+                }
+                else if (hasBboxChanged) {
+                    // Only position changed - mark as MOVED
+                    result.push({
+                        ...el,
+                        diff_status: 'MOVED',
+                    });
+                }
+                else if (hasContentChanged) {
+                    // Only content changed - mark as MODIFIED
+                    result.push({
+                        ...el,
+                        diff_status: 'MODIFIED',
+                    });
+                }
+                else {
+                    // No change - don't set diff_status (frontend expects undefined)
+                    result.push({
+                        ...el,
+                        diff_status: undefined,
+                    });
+                }
+            }
+        }
+        // Process removed elements (existed in previous but not in current)
+        for (const prevId of previousIds) {
+            if (!currentIds.has(prevId)) {
+                const prevEl = previousById.get(prevId);
+                result.push({
+                    ...prevEl,
+                    diff_status: 'REMOVED',
+                });
+            }
+        }
+        return result;
+    }
+}
+exports.SnapshotDiff = SnapshotDiff;
+//# sourceMappingURL=snapshot-diff.js.map

package/dist/snapshot-diff.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-diff.js","sourceRoot":"","sources":["../src/snapshot-diff.ts"],"names":[],"mappings":";AAAA;;;;;;GAMG;;;AAEH,yDAA8E;AAG9E;;GAEG;AACH,SAAS,aAAa,CAAC,EAAW;IAChC,OAAO;QACL,EAAE,EAAE,EAAE,CAAC,EAAE;QACT,IAAI,EAAE,EAAE,CAAC,IAAI;QACb,IAAI,EAAE,EAAE,CAAC,IAAI;QACb,IAAI,EAAE;YACJ,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;YACZ,CAAC,EAAE,EAAE,CAAC,IAAI,CAAC,CAAC;YACZ,KAAK,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK;YACpB,MAAM,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM;SACvB;QACD,WAAW,EAAE;YACX,UAAU,EAAE,EAAE,CAAC,WAAW,CAAC,UAAU;YACrC,YAAY,EAAE,EAAE,CAAC,WAAW,CAAC,YAAY;SAC1C;KACF,CAAC;AACJ,CAAC;AAED,MAAa,YAAY;IACvB;;;;;;;;;;OAUG;IACH,MAAM,CAAC,iBAAiB,CAAC,OAAiB,EAAE,QAA8B;QACxE,0DAA0D;QAC1D,IAAI,CAAC,QAAQ,EAAE,CAAC;YACd,OAAO,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC;gBACjC,GAAG,EAAE;gBACL,WAAW,EAAE,OAAgB;aAC9B,CAAC,CAAC,CAAC;QACN,CAAC;QAED,kCAAkC;QAClC,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,OAAO,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QACrE,MAAM,YAAY,GAAG,IAAI,GAAG,CAAC,QAAQ,CAAC,QAAQ,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,CAAC,EAAE,CAAC,EAAE,EAAE,EAAE,CAAC,CAAC,CAAC,CAAC;QAEvE,MAAM,UAAU,GAAG,IAAI,GAAG,CAAC,WAAW,CAAC,IAAI,EAAE,CAAC,CAAC;QAC/C,MAAM,WAAW,GAAG,IAAI,GAAG,CAAC,YAAY,CAAC,IAAI,EAAE,CAAC,CAAC;QAEjD,MAAM,MAAM,GAAc,EAAE,CAAC;QAE7B,2BAA2B;QAC3B,KAAK,MAAM,EAAE,IAAI,OAAO,CAAC,QAAQ,EAAE,CAAC;YAClC,IAAI,CAAC,WAAW,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;gBAC5B,iCAAiC;gBACjC,MAAM,CAAC,IAAI,CAAC;oBACV,GAAG,EAAE;oBACL,WAAW,EAAE,OAAO;iBACrB,CAAC,CAAC;YACL,CAAC;iBAAM,CAAC;gBACN,6EAA6E;gBAC7E,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,EAAE,CAAC,EAAE,CAAE,CAAC;gBAExC,sDAAsD;gBACtD,MAAM,MAAM,GAAG,aAAa,CAAC,EAAE,CAAC,CAAC;gBACjC,MAAM,UAAU,GAAG,aAAa,CAAC,MAAM,CAAC,CAAC;gBAEzC,MAAM,cAAc,GAAG,IAAA,8BAAW,EAAC,MAAM,CAAC,IAAK,EAAE,UAAU,CAAC,IAAK,CAAC,CAAC;gBACnE,MAAM,iBAAiB,GAAG,IAAA,iCAAc,EAAC,MAAM,EAAE,UAAU,CAAC,CAAC;gBAE7D,IAAI,cAAc,IAAI,iBAAiB,EAAE,CAAC;oBACxC,uDAAuD;oBACvD,MAAM,CAAC,IAAI,CAAC;wBACV,GAAG,EAAE;wBACL,WAAW,EAAE,UAAU;qBACxB,CAAC,CAAC;gBACL,CAAC;qBAAM,IAAI,cAAc,EAAE,CAAC;oBAC1B,wCAAwC;oBACxC,MAAM,CAAC,IAAI,CAAC;wBACV,GAAG,EAAE;wBACL,WAAW,EAAE,OAAO;qBACrB,CAAC,CAAC;gBACL,CAAC;qBAAM,IAAI,iBAAiB,EAAE,CAAC;oBAC7B,0CAA0C;oBAC1C,MAAM,CAAC,IAAI,CAAC;wBACV,GAAG,EAAE;wBACL,WAAW,EAAE,UAAU;qBACxB,CAAC,CAAC;gBACL,CAAC;qBAAM,CAAC;oBACN,iEAAiE;oBACjE,MAAM,CAAC,IAAI,CAAC;wBACV,GAAG,EAAE;wBACL,WAAW,EAAE,SAAS;qBACvB,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;QACH,CAAC;QAED,oEAAoE;QACpE,KAAK,MAAM,MAAM,IAAI,WAAW,EAAE,CAAC;YACjC,IAAI,CAAC,UAAU,CAAC,GAAG,CAAC,MAAM,CAAC,EAAE,CAAC;gBAC5B,MAAM,MAAM,GAAG,YAAY,CAAC,GAAG,CAAC,MAAM,CAAE,CAAC;gBACzC,MAAM,CAAC,IAAI,CAAC;oBACV,GAAG,MAAM;oBACT,WAAW,EAAE,SAAS;iBACvB,CAAC,CAAC;YACL,CAAC;QACH,CAAC;QAED,OAAO,MAAM,CAAC;IAChB,CAAC;CACF;AA1FD,oCA0FC"}

package/dist/snapshot.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Snapshot functionality - calls window.sentience.snapshot() or server-side API
+ */
+import { IBrowser } from './protocols/browser-protocol';
+import { Snapshot } from './types';
+/**
+ * Structured error for server-side (gateway) snapshot failures.
+ *
+ * Keeps HTTP status/URL/response details available to callers for better logging/debugging.
+ */
+export declare class SnapshotGatewayError extends Error {
+    statusCode?: number;
+    url?: string;
+    requestId?: string;
+    responseText?: string;
+    cause?: unknown;
+    constructor(message: string, opts?: {
+        statusCode?: number;
+        url?: string;
+        requestId?: string;
+        responseText?: string;
+        cause?: unknown;
+    });
+    static snip(s: string | undefined, n?: number): string | undefined;
+}
+export interface SnapshotOptions {
+    screenshot?: boolean | {
+        format: 'png' | 'jpeg';
+        quality?: number;
+    };
+    limit?: number;
+    filter?: {
+        min_area?: number;
+        allowed_roles?: string[];
+        min_z_index?: number;
+    };
+    use_api?: boolean;
+    gatewayTimeoutMs?: number;
+    save_trace?: boolean;
+    trace_path?: string;
+    goal?: string;
+    show_overlay?: boolean;
+    show_grid?: boolean;
+    grid_id?: number | null;
+}
+export declare function snapshot(browser: IBrowser, options?: SnapshotOptions): Promise<Snapshot>;
+//# sourceMappingURL=snapshot.d.ts.map

package/dist/snapshot.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot.d.ts","sourceRoot":"","sources":["../src/snapshot.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,8BAA8B,CAAC;AACxD,OAAO,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAQnC;;;;GAIG;AACH,qBAAa,oBAAqB,SAAQ,KAAK;IACtC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,GAAG,CAAC,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,KAAK,CAAC,EAAE,OAAO,CAAC;gBAGrB,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;QACL,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,GAAG,CAAC,EAAE,MAAM,CAAC;QACb,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,YAAY,CAAC,EAAE,MAAM,CAAC;QACtB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB;IAWH,MAAM,CAAC,IAAI,CAAC,CAAC,EAAE,MAAM,GAAG,SAAS,EAAE,CAAC,GAAE,MAAY,GAAG,MAAM,GAAG,SAAS;CAKxE;AAED,MAAM,WAAW,eAAe;IAC9B,UAAU,CAAC,EAAE,OAAO,GAAG;QAAE,MAAM,EAAE,KAAK,GAAG,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;IACpE,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,CAAC,EAAE;QACP,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,aAAa,CAAC,EAAE,MAAM,EAAE,CAAC;QACzB,WAAW,CAAC,EAAE,MAAM,CAAC;KACtB,CAAC;IACF,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,YAAY,CAAC,EAAE,OAAO,CAAC;IACvB,SAAS,CAAC,EAAE,OAAO,CAAC;IACpB,OAAO,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;CACzB;AAsBD,wBAAsB,QAAQ,CAC5B,OAAO,EAAE,QAAQ,EACjB,OAAO,GAAE,eAAoB,GAC5B,OAAO,CAAC,QAAQ,CAAC,CAenB"}