feat: add session-based snapshot diffing to take_snapshot (--diff)

Author: natorion

src/McpContext.ts

@@ -728,6 +728,9 @@ export class McpContext implements Context {
     page: McpPage,
     verbose = false,
     devtoolsData: DevToolsData | undefined = undefined,
+    options: {
+      diff?: boolean;
+    } = {},
   ): Promise<void> {
     const rootNode = await page.pptrPage.accessibility.snapshot({
       includeIframes: true,
@@ -745,10 +748,20 @@ export class McpContext implements Context {
     let idCounter = 0;
     const idToNode = new Map<string, TextSnapshotNode>();
     const seenUniqueIds = new Set<string>();
-    const assignIds = (node: SerializedAXNode): TextSnapshotNode => {
+    const assignIds = (
+      node: SerializedAXNode,
+      parentId = 'root',
+      index = 0,
+    ): TextSnapshotNode => {
       let id = '';
-      // @ts-expect-error untyped loaderId & backendNodeId.
-      const uniqueBackendId = `${node.loaderId}_${node.backendNodeId}`;
+      const nodeAny = node as any;
+      // StaticText nodes often have unstable backendNodeIds in some contexts,
+      // or we might want to group them by their parent.
+      const uniqueBackendId =
+        nodeAny.backendNodeId && node.role !== 'StaticText'
+          ? `${nodeAny.loaderId}_${nodeAny.backendNodeId}`
+          : `${nodeAny.loaderId}_${nodeAny.role}_${parentId}_${index}`;
+
       if (uniqueBackendNodeIdToMcpId.has(uniqueBackendId)) {
         // Re-use MCP exposed ID if the uniqueId is the same.
         id = uniqueBackendNodeIdToMcpId.get(uniqueBackendId)!;
@@ -763,7 +776,7 @@ export class McpContext implements Context {
         ...node,
         id,
         children: node.children
-          ? node.children.map(child => assignIds(child))
+          ? node.children.map((child, i) => assignIds(child, id, i))
           : [],
       };
 
@@ -788,7 +801,38 @@ export class McpContext implements Context {
       hasSelectedElement: false,
       verbose,
     };
+
+    if (options.diff && page.lastSnapshot) {
+      const lastIdToNode = page.lastSnapshot.idToNode;
+      const added: string[] = [];
+      const changed: string[] = [];
+      const removed: string[] = [];
+
+      for (const [id, node] of idToNode) {
+        const lastNode = lastIdToNode.get(id);
+        if (!lastNode) {
+          added.push(id);
+        } else if (
+          node.name !== lastNode.name ||
+          node.value !== lastNode.value ||
+          node.description !== lastNode.description ||
+          node.role !== lastNode.role
+        ) {
+          changed.push(id);
+        }
+      }
+
+      for (const id of lastIdToNode.keys()) {
+        if (!idToNode.has(id)) {
+          removed.push(id);
+        }
+      }
+
+      snapshot.diff = {added, changed, removed};
+    }
+
     page.textSnapshot = snapshot;
+    page.lastSnapshot = snapshot;
     const data = devtoolsData ?? (await this.getDevToolsData(page));
     if (data?.cdpBackendNodeId) {
       snapshot.hasSelectedElement = true;

src/McpPage.ts

@@ -33,6 +33,7 @@ export class McpPage implements ContextPage {
 
   // Snapshot
   textSnapshot: TextSnapshot | null = null;
+  lastSnapshot: TextSnapshot | null = null;
   uniqueBackendNodeIdToMcpId = new Map<string, string>();
 
   // Emulation
@@ -45,14 +46,19 @@ export class McpPage implements ContextPage {
   // Dialog
   #dialog?: Dialog;
   #dialogHandler: (dialog: Dialog) => void;
+  #navigationHandler: () => void;
 
   constructor(page: Page, id: number) {
     this.pptrPage = page;
     this.id = id;
     this.#dialogHandler = (dialog: Dialog): void => {
       this.#dialog = dialog;
     };
+    this.#navigationHandler = (): void => {
+      this.lastSnapshot = null;
+    };
     page.on('dialog', this.#dialogHandler);
+    page.on('framenavigated', this.#navigationHandler);
   }
 
   get dialog(): Dialog | undefined {
@@ -93,6 +99,7 @@ export class McpPage implements ContextPage {
 
   dispose(): void {
     this.pptrPage.off('dialog', this.#dialogHandler);
+    this.pptrPage.off('framenavigated', this.#navigationHandler);
   }
 
   async getElementByUid(uid: string): Promise<ElementHandle<Element>> {

src/McpResponse.ts

@@ -276,6 +276,9 @@ export class McpResponse implements Response {
         this.#page,
         this.#snapshotParams.verbose,
         this.#devToolsData,
+        {
+          diff: this.#snapshotParams.diff,
+        },
       );
       const textSnapshot = this.#page.textSnapshot;
       if (textSnapshot) {