fix: improve ID stability and add diff reset notification

Author: natorion

scripts/post-build.ts

@@ -26,6 +26,7 @@ function main(): void {
 
   // Create i18n mock
   const i18nDir = path.join(BUILD_DIR, devtoolsFrontEndCorePath, 'i18n');
+  fs.mkdirSync(i18nDir, {recursive: true});
   const localesFile = path.join(i18nDir, 'locales.js');
   const localesContent = `
 export const LOCALES = [

src/McpContext.ts

@@ -757,10 +757,9 @@ export class McpContext implements Context {
       const nodeAny = node as unknown as Record<string, unknown>;
       // 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}_${node.role}_${parentId}_${index}`;
+      const uniqueBackendId = nodeAny.backendNodeId
+        ? `${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.
@@ -800,6 +799,7 @@ export class McpContext implements Context {
       idToNode,
       hasSelectedElement: false,
       verbose,
+      diffReset: !!(options.diff && !page.lastSnapshot),
     };
 
     if (options.diff && page.lastSnapshot) {

src/formatters/SnapshotFormatter.ts

@@ -27,6 +27,12 @@ export class SnapshotFormatter {
 Get a verbose snapshot to include all elements if you are interested in the selected element.\n\n`);
     }
 
+    if (this.#snapshot.diffReset) {
+      chunks.push(
+        'Note: no previous snapshot found for this page (cache may have been reset due to navigation). Returning full snapshot.\n\n',
+      );
+    }
+
     if (this.#snapshot.diff) {
       const {added, changed, removed} = this.#snapshot.diff;
       if (added.length === 0 && changed.length === 0 && removed.length === 0) {

src/types.ts

@@ -33,6 +33,7 @@ export interface TextSnapshot {
   // snapshot. This flag indicates if there is any selected element.
   hasSelectedElement: boolean;
   verbose: boolean;
+  diffReset?: boolean;
   diff?: {
     added: string[];
     removed: string[];

tests/McpContext.test.ts

@@ -180,6 +180,7 @@ describe('McpContext', () => {
         await page.pptrPage.goto('about:blank');
         await context.createTextSnapshot(page, false, undefined, {diff: true});
         assert.strictEqual(page.textSnapshot?.diff, undefined); // Should be reset
+        assert.strictEqual(page.textSnapshot?.diffReset, true);
       });
     });
   });