devlens-mcp 0.3.0

package/dist/src/server.js

@@ -0,0 +1,176 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startServer = startServer;
+const index_js_1 = require("@modelcontextprotocol/sdk/server/index.js");
+const stdio_js_1 = require("@modelcontextprotocol/sdk/server/stdio.js");
+const types_js_1 = require("@modelcontextprotocol/sdk/types.js");
+const device_manager_js_1 = require("./platform/device-manager.js");
+const ref_registry_js_1 = require("./snapshot/ref-registry.js");
+const devlens_config_js_1 = require("./config/devlens-config.js");
+const ds_tools_js_1 = require("./tools/ds-tools.js");
+const device_tools_js_1 = require("./tools/device-tools.js");
+const snapshot_tools_js_1 = require("./tools/snapshot-tools.js");
+const interaction_tools_js_1 = require("./tools/interaction-tools.js");
+const screenshot_tools_js_1 = require("./tools/screenshot-tools.js");
+const app_tools_js_1 = require("./tools/app-tools.js");
+const metro_tools_js_1 = require("./tools/metro-tools.js");
+const navigation_tools_js_1 = require("./tools/navigation-tools.js");
+async function startServer() {
+    const server = new index_js_1.Server({
+        name: "devlens-mcp",
+        version: "0.3.0",
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    // Load config (from DEVLENS_CONFIG env var or ./devlens.config.json)
+    const devlensConfig = await (0, devlens_config_js_1.loadDevLensConfig)();
+    // Shared state
+    const deviceManager = new device_manager_js_1.DeviceManager();
+    const refRegistry = new ref_registry_js_1.RefRegistry();
+    const metroPort = parseInt(process.env.METRO_PORT || "8081", 10);
+    // Create tool handlers
+    const dsHandlers = (0, ds_tools_js_1.createDsToolHandlers)(devlensConfig.designSystem);
+    const deviceHandlers = (0, device_tools_js_1.createDeviceToolHandlers)(deviceManager);
+    const { handlers: snapshotHandlers, resetPreviousSnapshot } = (0, snapshot_tools_js_1.createSnapshotToolHandlers)(deviceManager, refRegistry);
+    const interactionHandlers = (0, interaction_tools_js_1.createInteractionToolHandlers)(deviceManager, refRegistry, resetPreviousSnapshot);
+    const screenshotHandlers = (0, screenshot_tools_js_1.createScreenshotToolHandlers)(deviceManager, refRegistry);
+    const appHandlers = (0, app_tools_js_1.createAppToolHandlers)(deviceManager);
+    const metroHandlers = (0, metro_tools_js_1.createMetroToolHandlers)(metroPort, deviceManager);
+    const navigationHandlers = (0, navigation_tools_js_1.createNavigationToolHandlers)(deviceManager, refRegistry, resetPreviousSnapshot);
+    // Merge all tool schemas
+    const allSchemas = {
+        ...ds_tools_js_1.dsToolSchemas,
+        ...device_tools_js_1.deviceToolSchemas,
+        ...snapshot_tools_js_1.snapshotToolSchemas,
+        ...interaction_tools_js_1.interactionToolSchemas,
+        ...screenshot_tools_js_1.screenshotToolSchemas,
+        ...app_tools_js_1.appToolSchemas,
+        ...metro_tools_js_1.metroToolSchemas,
+        ...navigation_tools_js_1.navigationToolSchemas,
+    };
+    // Merge all handlers
+    const allHandlers = {
+        ...dsHandlers,
+        ...deviceHandlers,
+        ...snapshotHandlers,
+        ...interactionHandlers,
+        ...screenshotHandlers,
+        ...appHandlers,
+        ...metroHandlers,
+        ...navigationHandlers,
+    };
+    // Register tools/list handler
+    server.setRequestHandler(types_js_1.ListToolsRequestSchema, async () => {
+        return {
+            tools: Object.entries(allSchemas).map(([name, schema]) => ({
+                name,
+                description: schema.description,
+                inputSchema: zodToJsonSchema(schema.parameters),
+            })),
+        };
+    });
+    // Register tools/call handler
+    server.setRequestHandler(types_js_1.CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        const handler = allHandlers[name];
+        if (!handler) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Unknown tool: ${name}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+        try {
+            // Validate params with Zod schema
+            const schema = allSchemas[name];
+            const validatedArgs = schema.parameters.parse(args || {});
+            return await handler(validatedArgs);
+        }
+        catch (error) {
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `Error: ${error.message || String(error)}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    // Connect via stdio transport
+    const transport = new stdio_js_1.StdioServerTransport();
+    await server.connect(transport);
+    return server;
+}
+/**
+ * Convert a Zod schema to JSON Schema for MCP tool registration.
+ * This is a simplified converter that handles the common cases.
+ */
+function zodToJsonSchema(schema) {
+    // Use Zod's built-in JSON schema support if available
+    if (schema._def) {
+        return convertZodDef(schema._def);
+    }
+    return { type: "object", properties: {} };
+}
+function convertZodDef(def) {
+    switch (def.typeName) {
+        case "ZodObject": {
+            const properties = {};
+            const required = [];
+            for (const [key, value] of Object.entries(def.shape())) {
+                const propDef = value._def;
+                if (propDef.typeName === "ZodOptional" || propDef.typeName === "ZodDefault") {
+                    properties[key] = convertZodDef(propDef.typeName === "ZodDefault" ? propDef.innerType._def : propDef.innerType._def);
+                }
+                else {
+                    properties[key] = convertZodDef(propDef);
+                    required.push(key);
+                }
+                // Add description from Zod describe()
+                if (propDef.description) {
+                    properties[key].description = propDef.description;
+                }
+                else if (value.description) {
+                    properties[key].description = value.description;
+                }
+            }
+            return {
+                type: "object",
+                properties,
+                ...(required.length > 0 ? { required } : {}),
+            };
+        }
+        case "ZodString":
+            return { type: "string", ...(def.description ? { description: def.description } : {}) };
+        case "ZodNumber":
+            return { type: "number", ...(def.description ? { description: def.description } : {}) };
+        case "ZodBoolean":
+            return { type: "boolean", ...(def.description ? { description: def.description } : {}) };
+        case "ZodEnum":
+            return { type: "string", enum: def.values, ...(def.description ? { description: def.description } : {}) };
+        case "ZodArray":
+            return {
+                type: "array",
+                items: convertZodDef(def.type._def),
+                ...(def.description ? { description: def.description } : {}),
+            };
+        case "ZodDefault":
+            return {
+                ...convertZodDef(def.innerType._def),
+                default: def.defaultValue(),
+            };
+        case "ZodOptional":
+            return convertZodDef(def.innerType._def);
+        default:
+            return {};
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/src/server.js.map

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

package/dist/src/snapshot/formatter.d.ts

@@ -0,0 +1,18 @@
+import type { SnapshotNode } from "../platform/device.js";
+/**
+ * Formats a SnapshotNode tree into a YAML-like text representation
+ * that LLMs can easily parse and reason about.
+ *
+ * Output format (inspired by Playwright MCP):
+ *
+ * - FrameLayout
+ *   - LinearLayout
+ *     - TextView "Hello World" [ref=e1]
+ *     - Button "Submit" [ref=e2]
+ *     - EditText "Email" [ref=e3] [focused]
+ *   - RecyclerView [ref=e4]
+ *     - CardView
+ *       - TextView "Item 1" [ref=e5]
+ */
+export declare function formatSnapshot(root: SnapshotNode, nodeToRef: Map<SnapshotNode, string>): string;
+//# sourceMappingURL=formatter.d.ts.map

package/dist/src/snapshot/formatter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"formatter.d.ts","sourceRoot":"","sources":["../../../src/snapshot/formatter.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,cAAc,CAC5B,IAAI,EAAE,YAAY,EAClB,SAAS,EAAE,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC,GACnC,MAAM,CAIR"}

package/dist/src/snapshot/formatter.js

@@ -0,0 +1,86 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.formatSnapshot = formatSnapshot;
+/**
+ * Formats a SnapshotNode tree into a YAML-like text representation
+ * that LLMs can easily parse and reason about.
+ *
+ * Output format (inspired by Playwright MCP):
+ *
+ * - FrameLayout
+ *   - LinearLayout
+ *     - TextView "Hello World" [ref=e1]
+ *     - Button "Submit" [ref=e2]
+ *     - EditText "Email" [ref=e3] [focused]
+ *   - RecyclerView [ref=e4]
+ *     - CardView
+ *       - TextView "Item 1" [ref=e5]
+ */
+function formatSnapshot(root, nodeToRef) {
+    const lines = [];
+    formatNode(root, nodeToRef, 0, lines);
+    return lines.join("\n");
+}
+function formatNode(node, nodeToRef, depth, lines) {
+    const indent = "  ".repeat(depth);
+    const parts = [];
+    // Type
+    parts.push(node.type);
+    // Text content
+    if (node.text) {
+        parts.push(`"${truncate(node.text, 60)}"`);
+    }
+    // Accessibility label (if different from text)
+    if (node.label && node.label !== node.text) {
+        parts.push(`label="${truncate(node.label, 40)}"`);
+    }
+    // Annotations
+    const annotations = [];
+    // Ref
+    const ref = nodeToRef.get(node);
+    if (ref) {
+        annotations.push(`ref=${ref}`);
+    }
+    // State annotations
+    if (node.focused)
+        annotations.push("focused");
+    if (node.value)
+        annotations.push(`value="${node.value}"`);
+    if (node.enabled === false)
+        annotations.push("disabled");
+    if (node.resourceId) {
+        const shortId = node.resourceId.includes("/")
+            ? node.resourceId.split("/").pop()
+            : node.resourceId;
+        annotations.push(`id="${shortId}"`);
+    }
+    if (annotations.length > 0) {
+        parts.push(`[${annotations.join("] [")}]`);
+    }
+    // Build the line
+    const line = `${indent}- ${parts.join(" ")}`;
+    // Only include nodes that have refs, text, labels, or children with refs
+    if (ref || node.text || node.label || hasRefInSubtree(node, nodeToRef)) {
+        lines.push(line);
+    }
+    // Recurse into children
+    for (const child of node.children) {
+        formatNode(child, nodeToRef, depth + 1, lines);
+    }
+}
+/** Check if any descendant has a ref assigned */
+function hasRefInSubtree(node, nodeToRef) {
+    for (const child of node.children) {
+        if (nodeToRef.has(child))
+            return true;
+        if (hasRefInSubtree(child, nodeToRef))
+            return true;
+    }
+    return false;
+}
+function truncate(str, maxLen) {
+    if (str.length <= maxLen)
+        return str;
+    return str.slice(0, maxLen - 3) + "...";
+}
+//# sourceMappingURL=formatter.js.map

package/dist/src/snapshot/formatter.js.map

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

package/dist/src/snapshot/ref-registry.d.ts

@@ -0,0 +1,67 @@
+import type { SnapshotNode, Bounds } from "../platform/device.js";
+/**
+ * RefRegistry — the Playwright-style ref assignment system.
+ *
+ * Assigns monotonically increasing refs (e1, e2, ...) to every interactive
+ * or meaningful node in the accessibility tree. Maintains a map from ref
+ * to node info (bounds, center coords) so interaction tools can resolve
+ * "tap ref=e5" to actual screen coordinates.
+ */
+export interface RefEntry {
+    ref: string;
+    node: SnapshotNode;
+    centerX: number;
+    centerY: number;
+    bounds: Bounds;
+}
+export interface ValidationIssue {
+    type: "zero-size" | "invisible" | "empty-container";
+    nodeType: string;
+    text?: string;
+    label?: string;
+    resourceId?: string;
+    bounds: Bounds;
+    detail: string;
+}
+export interface ValidationReport {
+    issues: ValidationIssue[];
+    totalNodes: number;
+    visibleNodes: number;
+    zeroSizeNodes: number;
+    interactiveNodes: number;
+}
+export declare class RefRegistry {
+    private refMap;
+    private counter;
+    /** Clear all refs and reset counter (call before each new snapshot) */
+    reset(): void;
+    /**
+     * Walk the snapshot tree and assign refs to all interactive or content-bearing nodes.
+     * Returns a new tree with refs attached (as annotations in the formatter output).
+     */
+    assignRefs(root: SnapshotNode): Map<SnapshotNode, string>;
+    private walkAndAssign;
+    /** Determine if a node should get a ref */
+    private shouldAssignRef;
+    /** Resolve a ref string to its entry (coordinates + node info) */
+    resolve(ref: string): RefEntry | undefined;
+    /** Get all current ref entries */
+    getAllRefs(): RefEntry[];
+    /** Get the total number of assigned refs */
+    get size(): number;
+    /**
+     * Validate the snapshot tree for visibility issues.
+     * Flags zero-size elements that should be visible, explicitly invisible elements,
+     * and empty containers that might indicate missing content.
+     */
+    validateTree(root: SnapshotNode): ValidationReport;
+    /**
+     * Search the full snapshot tree (including zero-size nodes) for text/label matches.
+     * Used by find_element to detect invisible elements that the refMap skips.
+     */
+    findInTree(root: SnapshotNode, query: {
+        text?: string;
+        label?: string;
+    }): SnapshotNode[];
+}
+//# sourceMappingURL=ref-registry.d.ts.map

package/dist/src/snapshot/ref-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref-registry.d.ts","sourceRoot":"","sources":["../../../src/snapshot/ref-registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,EAAE,MAAM,uBAAuB,CAAC;AAElE;;;;;;;GAOG;AAEH,MAAM,WAAW,QAAQ;IACvB,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,YAAY,CAAC;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,eAAe;IAC9B,IAAI,EAAE,WAAW,GAAG,WAAW,GAAG,iBAAiB,CAAC;IACpD,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAgB;IAC/B,MAAM,EAAE,eAAe,EAAE,CAAC;IAC1B,UAAU,EAAE,MAAM,CAAC;IACnB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,qBAAa,WAAW;IACtB,OAAO,CAAC,MAAM,CAAoC;IAClD,OAAO,CAAC,OAAO,CAAa;IAE5B,uEAAuE;IACvE,KAAK,IAAI,IAAI;IAKb;;;OAGG;IACH,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,GAAG,CAAC,YAAY,EAAE,MAAM,CAAC;IAOzD,OAAO,CAAC,aAAa;IAwBrB,2CAA2C;IAC3C,OAAO,CAAC,eAAe;IAiBvB,kEAAkE;IAClE,OAAO,CAAC,GAAG,EAAE,MAAM,GAAG,QAAQ,GAAG,SAAS;IAI1C,kCAAkC;IAClC,UAAU,IAAI,QAAQ,EAAE;IAIxB,4CAA4C;IAC5C,IAAI,IAAI,IAAI,MAAM,CAEjB;IAED;;;;OAIG;IACH,YAAY,CAAC,IAAI,EAAE,YAAY,GAAG,gBAAgB;IA4ElD;;;OAGG;IACH,UAAU,CACR,IAAI,EAAE,YAAY,EAClB,KAAK,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,KAAK,CAAC,EAAE,MAAM,CAAA;KAAE,GACvC,YAAY,EAAE;CA0BlB"}

package/dist/src/snapshot/ref-registry.js

@@ -0,0 +1,169 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RefRegistry = void 0;
+class RefRegistry {
+    refMap = new Map();
+    counter = 0;
+    /** Clear all refs and reset counter (call before each new snapshot) */
+    reset() {
+        this.refMap.clear();
+        this.counter = 0;
+    }
+    /**
+     * Walk the snapshot tree and assign refs to all interactive or content-bearing nodes.
+     * Returns a new tree with refs attached (as annotations in the formatter output).
+     */
+    assignRefs(root) {
+        this.reset();
+        const nodeToRef = new Map();
+        this.walkAndAssign(root, nodeToRef);
+        return nodeToRef;
+    }
+    walkAndAssign(node, nodeToRef) {
+        if (this.shouldAssignRef(node)) {
+            const ref = `e${++this.counter}`;
+            const centerX = node.bounds.x + node.bounds.width / 2;
+            const centerY = node.bounds.y + node.bounds.height / 2;
+            this.refMap.set(ref, {
+                ref,
+                node,
+                centerX,
+                centerY,
+                bounds: node.bounds,
+            });
+            nodeToRef.set(node, ref);
+        }
+        for (const child of node.children) {
+            this.walkAndAssign(child, nodeToRef);
+        }
+    }
+    /** Determine if a node should get a ref */
+    shouldAssignRef(node) {
+        // Skip invisible/zero-size elements
+        if (node.bounds.width === 0 || node.bounds.height === 0)
+            return false;
+        // Always assign refs to interactive elements
+        if (node.interactive)
+            return true;
+        // Assign refs to elements with meaningful text content
+        if (node.text && node.text.trim().length > 0)
+            return true;
+        // Assign refs to elements with accessibility labels
+        if (node.label && node.label.trim().length > 0)
+            return true;
+        // Skip purely structural containers
+        return false;
+    }
+    /** Resolve a ref string to its entry (coordinates + node info) */
+    resolve(ref) {
+        return this.refMap.get(ref);
+    }
+    /** Get all current ref entries */
+    getAllRefs() {
+        return Array.from(this.refMap.values());
+    }
+    /** Get the total number of assigned refs */
+    get size() {
+        return this.refMap.size;
+    }
+    /**
+     * Validate the snapshot tree for visibility issues.
+     * Flags zero-size elements that should be visible, explicitly invisible elements,
+     * and empty containers that might indicate missing content.
+     */
+    validateTree(root) {
+        const issues = [];
+        let totalNodes = 0;
+        let visibleNodes = 0;
+        let interactiveNodes = 0;
+        let zeroSizeNodes = 0;
+        const walk = (node) => {
+            totalNodes++;
+            const isZeroSize = node.bounds.width === 0 || node.bounds.height === 0;
+            if (isZeroSize) {
+                zeroSizeNodes++;
+                // Only flag if the node has content that SHOULD be visible
+                if (node.text || node.label || node.interactive) {
+                    issues.push({
+                        type: "zero-size",
+                        nodeType: node.type,
+                        text: node.text,
+                        label: node.label,
+                        resourceId: node.resourceId,
+                        bounds: node.bounds,
+                        detail: `${node.type}${node.text ? ` "${node.text}"` : ""}${node.label ? ` label="${node.label}"` : ""}` +
+                            ` has zero size (${node.bounds.width}x${node.bounds.height}) — renders as invisible`,
+                    });
+                }
+            }
+            else {
+                visibleNodes++;
+            }
+            if (node.visible === false) {
+                issues.push({
+                    type: "invisible",
+                    nodeType: node.type,
+                    text: node.text,
+                    label: node.label,
+                    resourceId: node.resourceId,
+                    bounds: node.bounds,
+                    detail: `${node.type}${node.text ? ` "${node.text}"` : ""} has visible=false`,
+                });
+            }
+            if (node.interactive)
+                interactiveNodes++;
+            // Empty container with a resource ID — likely an intentional component
+            // that should have content (e.g., missing icon, empty image)
+            if (node.children.length === 0 &&
+                node.resourceId &&
+                !node.text &&
+                !node.label &&
+                !isZeroSize) {
+                issues.push({
+                    type: "empty-container",
+                    nodeType: node.type,
+                    resourceId: node.resourceId,
+                    bounds: node.bounds,
+                    detail: `${node.type} id="${node.resourceId}" is an empty container (no children, no text) — may be a missing icon or placeholder`,
+                });
+            }
+            for (const child of node.children) {
+                walk(child);
+            }
+        };
+        walk(root);
+        return { issues, totalNodes, visibleNodes, zeroSizeNodes, interactiveNodes };
+    }
+    /**
+     * Search the full snapshot tree (including zero-size nodes) for text/label matches.
+     * Used by find_element to detect invisible elements that the refMap skips.
+     */
+    findInTree(root, query) {
+        const matches = [];
+        const walk = (node) => {
+            const isZeroSize = node.bounds.width === 0 || node.bounds.height === 0;
+            if (isZeroSize) {
+                let matched = false;
+                if (query.text && node.text) {
+                    matched = node.text
+                        .toLowerCase()
+                        .includes(query.text.toLowerCase());
+                }
+                if (query.label && node.label) {
+                    matched =
+                        matched ||
+                            node.label.toLowerCase().includes(query.label.toLowerCase());
+                }
+                if (matched)
+                    matches.push(node);
+            }
+            for (const child of node.children) {
+                walk(child);
+            }
+        };
+        walk(root);
+        return matches;
+    }
+}
+exports.RefRegistry = RefRegistry;
+//# sourceMappingURL=ref-registry.js.map

package/dist/src/snapshot/ref-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ref-registry.js","sourceRoot":"","sources":["../../../src/snapshot/ref-registry.ts"],"names":[],"mappings":";;;AAqCA,MAAa,WAAW;IACd,MAAM,GAA0B,IAAI,GAAG,EAAE,CAAC;IAC1C,OAAO,GAAW,CAAC,CAAC;IAE5B,uEAAuE;IACvE,KAAK;QACH,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC;QACpB,IAAI,CAAC,OAAO,GAAG,CAAC,CAAC;IACnB,CAAC;IAED;;;OAGG;IACH,UAAU,CAAC,IAAkB;QAC3B,IAAI,CAAC,KAAK,EAAE,CAAC;QACb,MAAM,SAAS,GAAG,IAAI,GAAG,EAAwB,CAAC;QAClD,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,SAAS,CAAC,CAAC;QACpC,OAAO,SAAS,CAAC;IACnB,CAAC;IAEO,aAAa,CACnB,IAAkB,EAClB,SAAoC;QAEpC,IAAI,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,EAAE,CAAC;YAC/B,MAAM,GAAG,GAAG,IAAI,EAAE,IAAI,CAAC,OAAO,EAAE,CAAC;YACjC,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,KAAK,GAAG,CAAC,CAAC;YACtD,MAAM,OAAO,GAAG,IAAI,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,MAAM,CAAC,MAAM,GAAG,CAAC,CAAC;YAEvD,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,EAAE;gBACnB,GAAG;gBACH,IAAI;gBACJ,OAAO;gBACP,OAAO;gBACP,MAAM,EAAE,IAAI,CAAC,MAAM;aACpB,CAAC,CAAC;YACH,SAAS,CAAC,GAAG,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;QAC3B,CAAC;QAED,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;YAClC,IAAI,CAAC,aAAa,CAAC,KAAK,EAAE,SAAS,CAAC,CAAC;QACvC,CAAC;IACH,CAAC;IAED,2CAA2C;IACnC,eAAe,CAAC,IAAkB;QACxC,oCAAoC;QACpC,IAAI,IAAI,CAAC,MAAM,CAAC,KAAK,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC;YAAE,OAAO,KAAK,CAAC;QAEtE,6CAA6C;QAC7C,IAAI,IAAI,CAAC,WAAW;YAAE,OAAO,IAAI,CAAC;QAElC,uDAAuD;QACvD,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAE1D,oDAAoD;QACpD,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,CAAC,MAAM,GAAG,CAAC;YAAE,OAAO,IAAI,CAAC;QAE5D,oCAAoC;QACpC,OAAO,KAAK,CAAC;IACf,CAAC;IAED,kEAAkE;IAClE,OAAO,CAAC,GAAW;QACjB,OAAO,IAAI,CAAC,MAAM,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC9B,CAAC;IAED,kCAAkC;IAClC,UAAU;QACR,OAAO,KAAK,CAAC,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC;IAC1C,CAAC;IAED,4CAA4C;IAC5C,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;IAED;;;;OAIG;IACH,YAAY,CAAC,IAAkB;QAC7B,MAAM,MAAM,GAAsB,EAAE,CAAC;QACrC,IAAI,UAAU,GAAG,CAAC,CAAC;QACnB,IAAI,YAAY,GAAG,CAAC,CAAC;QACrB,IAAI,gBAAgB,GAAG,CAAC,CAAC;QACzB,IAAI,aAAa,GAAG,CAAC,CAAC;QAEtB,MAAM,IAAI,GAAG,CAAC,IAAkB,EAAQ,EAAE;YACxC,UAAU,EAAE,CAAC;YAEb,MAAM,UAAU,GACd,IAAI,CAAC,MAAM,CAAC,KAAK,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC;YAEtD,IAAI,UAAU,EAAE,CAAC;gBACf,aAAa,EAAE,CAAC;gBAChB,2DAA2D;gBAC3D,IAAI,IAAI,CAAC,IAAI,IAAI,IAAI,CAAC,KAAK,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;oBAChD,MAAM,CAAC,IAAI,CAAC;wBACV,IAAI,EAAE,WAAW;wBACjB,QAAQ,EAAE,IAAI,CAAC,IAAI;wBACnB,IAAI,EAAE,IAAI,CAAC,IAAI;wBACf,KAAK,EAAE,IAAI,CAAC,KAAK;wBACjB,UAAU,EAAE,IAAI,CAAC,UAAU;wBAC3B,MAAM,EAAE,IAAI,CAAC,MAAM;wBACnB,MAAM,EACJ,GAAG,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,WAAW,IAAI,CAAC,KAAK,GAAG,CAAC,CAAC,CAAC,EAAE,EAAE;4BAChG,mBAAmB,IAAI,CAAC,MAAM,CAAC,KAAK,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,0BAA0B;qBACvF,CAAC,CAAC;gBACL,CAAC;YACH,CAAC;iBAAM,CAAC;gBACN,YAAY,EAAE,CAAC;YACjB,CAAC;YAED,IAAI,IAAI,CAAC,OAAO,KAAK,KAAK,EAAE,CAAC;gBAC3B,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,WAAW;oBACjB,QAAQ,EAAE,IAAI,CAAC,IAAI;oBACnB,IAAI,EAAE,IAAI,CAAC,IAAI;oBACf,KAAK,EAAE,IAAI,CAAC,KAAK;oBACjB,UAAU,EAAE,IAAI,CAAC,UAAU;oBAC3B,MAAM,EAAE,IAAI,CAAC,MAAM;oBACnB,MAAM,EACJ,GAAG,IAAI,CAAC,IAAI,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,IAAI,CAAC,IAAI,GAAG,CAAC,CAAC,CAAC,EAAE,oBAAoB;iBACxE,CAAC,CAAC;YACL,CAAC;YAED,IAAI,IAAI,CAAC,WAAW;gBAAE,gBAAgB,EAAE,CAAC;YAEzC,uEAAuE;YACvE,6DAA6D;YAC7D,IACE,IAAI,CAAC,QAAQ,CAAC,MAAM,KAAK,CAAC;gBAC1B,IAAI,CAAC,UAAU;gBACf,CAAC,IAAI,CAAC,IAAI;gBACV,CAAC,IAAI,CAAC,KAAK;gBACX,CAAC,UAAU,EACX,CAAC;gBACD,MAAM,CAAC,IAAI,CAAC;oBACV,IAAI,EAAE,iBAAiB;oBACvB,QAAQ,EAAE,IAAI,CAAC,IAAI;oBACnB,UAAU,EAAE,IAAI,CAAC,UAAU;oBAC3B,MAAM,EAAE,IAAI,CAAC,MAAM;oBACnB,MAAM,EACJ,GAAG,IAAI,CAAC,IAAI,QAAQ,IAAI,CAAC,UAAU,uFAAuF;iBAC7H,CAAC,CAAC;YACL,CAAC;YAED,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAClC,IAAI,CAAC,KAAK,CAAC,CAAC;YACd,CAAC;QACH,CAAC,CAAC;QAEF,IAAI,CAAC,IAAI,CAAC,CAAC;QACX,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,YAAY,EAAE,aAAa,EAAE,gBAAgB,EAAE,CAAC;IAC/E,CAAC;IAED;;;OAGG;IACH,UAAU,CACR,IAAkB,EAClB,KAAwC;QAExC,MAAM,OAAO,GAAmB,EAAE,CAAC;QACnC,MAAM,IAAI,GAAG,CAAC,IAAkB,EAAQ,EAAE;YACxC,MAAM,UAAU,GACd,IAAI,CAAC,MAAM,CAAC,KAAK,KAAK,CAAC,IAAI,IAAI,CAAC,MAAM,CAAC,MAAM,KAAK,CAAC,CAAC;YACtD,IAAI,UAAU,EAAE,CAAC;gBACf,IAAI,OAAO,GAAG,KAAK,CAAC;gBACpB,IAAI,KAAK,CAAC,IAAI,IAAI,IAAI,CAAC,IAAI,EAAE,CAAC;oBAC5B,OAAO,GAAG,IAAI,CAAC,IAAI;yBAChB,WAAW,EAAE;yBACb,QAAQ,CAAC,KAAK,CAAC,IAAI,CAAC,WAAW,EAAE,CAAC,CAAC;gBACxC,CAAC;gBACD,IAAI,KAAK,CAAC,KAAK,IAAI,IAAI,CAAC,KAAK,EAAE,CAAC;oBAC9B,OAAO;wBACL,OAAO;4BACP,IAAI,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,QAAQ,CAAC,KAAK,CAAC,KAAK,CAAC,WAAW,EAAE,CAAC,CAAC;gBACjE,CAAC;gBACD,IAAI,OAAO;oBAAE,OAAO,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;YAClC,CAAC;YACD,KAAK,MAAM,KAAK,IAAI,IAAI,CAAC,QAAQ,EAAE,CAAC;gBAClC,IAAI,CAAC,KAAK,CAAC,CAAC;YACd,CAAC;QACH,CAAC,CAAC;QACF,IAAI,CAAC,IAAI,CAAC,CAAC;QACX,OAAO,OAAO,CAAC;IACjB,CAAC;CACF;AAhMD,kCAgMC"}

package/dist/src/snapshot/snapshot-differ.d.ts

@@ -0,0 +1,57 @@
+import type { SnapshotNode } from "../platform/device.js";
+/**
+ * Incremental snapshot differ — compares two snapshot trees and returns
+ * only the changed portions. Saves 60-80% tokens in iterative workflows.
+ */
+export interface SnapshotDiff {
+    /** Nodes that were added since the last snapshot */
+    added: SnapshotNode[];
+    /** Nodes that were removed since the last snapshot */
+    removed: SnapshotNode[];
+    /** Nodes whose properties changed (text, value, focus, etc.) */
+    changed: Array<{
+        node: SnapshotNode;
+        changes: string[];
+    }>;
+    /** Elements that are the same content but moved to a different position */
+    moved: Array<{
+        node: SnapshotNode;
+        from: {
+            x: number;
+            y: number;
+        };
+        to: {
+            x: number;
+            y: number;
+        };
+        deltaX: number;
+        deltaY: number;
+    }>;
+    /** Elements that kept position but changed size */
+    resized: Array<{
+        node: SnapshotNode;
+        from: {
+            width: number;
+            height: number;
+        };
+        to: {
+            width: number;
+            height: number;
+        };
+    }>;
+    /** Whether the tree structure changed significantly */
+    structuralChange: boolean;
+}
+/**
+ * Compute a diff between two snapshot trees.
+ *
+ * Identity matching: uses content signature (type + resourceId + text + label).
+ * Elements with matching content but different position are reported as "moved".
+ * Elements with matching content+position but different size are reported as "resized".
+ * Elements present in current but not previous are "added".
+ * Elements present in previous but not current are "removed".
+ */
+export declare function diffSnapshots(previous: SnapshotNode, current: SnapshotNode): SnapshotDiff;
+/** Format a diff for LLM consumption */
+export declare function formatDiff(diff: SnapshotDiff): string;
+//# sourceMappingURL=snapshot-differ.d.ts.map

package/dist/src/snapshot/snapshot-differ.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"snapshot-differ.d.ts","sourceRoot":"","sources":["../../../src/snapshot/snapshot-differ.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC;AAE1D;;;GAGG;AAEH,MAAM,WAAW,YAAY;IAC3B,oDAAoD;IACpD,KAAK,EAAE,YAAY,EAAE,CAAC;IACtB,sDAAsD;IACtD,OAAO,EAAE,YAAY,EAAE,CAAC;IACxB,gEAAgE;IAChE,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,YAAY,CAAC;QACnB,OAAO,EAAE,MAAM,EAAE,CAAC;KACnB,CAAC,CAAC;IACH,2EAA2E;IAC3E,KAAK,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,YAAY,CAAC;QACnB,IAAI,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAC/B,EAAE,EAAE;YAAE,CAAC,EAAE,MAAM,CAAC;YAAC,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC;QAC7B,MAAM,EAAE,MAAM,CAAC;QACf,MAAM,EAAE,MAAM,CAAC;KAChB,CAAC,CAAC;IACH,mDAAmD;IACnD,OAAO,EAAE,KAAK,CAAC;QACb,IAAI,EAAE,YAAY,CAAC;QACnB,IAAI,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;QACxC,EAAE,EAAE;YAAE,KAAK,EAAE,MAAM,CAAC;YAAC,MAAM,EAAE,MAAM,CAAA;SAAE,CAAC;KACvC,CAAC,CAAC;IACH,uDAAuD;IACvD,gBAAgB,EAAE,OAAO,CAAC;CAC3B;AAWD;;;;;;;;GAQG;AACH,wBAAgB,aAAa,CAC3B,QAAQ,EAAE,YAAY,EACtB,OAAO,EAAE,YAAY,GACpB,YAAY,CAyEd;AAkCD,wCAAwC;AACxC,wBAAgB,UAAU,CAAC,IAAI,EAAE,YAAY,GAAG,MAAM,CAuDrD"}