From 254de089ee468795bac175d99e09ddaec4ac1469 Mon Sep 17 00:00:00 2001
From: amankumarsingh77 <amankumarsingh7702@gmail.com>
Date: Tue, 28 Jul 2026 19:50:02 +0530
Subject: fix(domains): keep element refs stable across a mutation
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

interactiveDiff re-assigned refs by tree position after every fill, click and
select, so any element appearing or disappearing shifted the numbering and a ref
the agent was still holding silently resolved to a different element — while the
tools kept promising that refs survive re-renders. Refs are now carried over by
backendNodeId and only genuinely new elements draw a new number.

Report: docs/superpowers/reports/2026-07-26-bug-audit.md#f6

Co-Authored-By: Claude Opus 5 (1M context) <noreply@anthropic.com>
---
 src/cdp/session.ts         |  5 +++++
 src/domains/ref-resolve.ts | 17 ++++++++++++++---
 2 files changed, 19 insertions(+), 3 deletions(-)

(limited to 'src')

diff --git a/src/cdp/session.ts b/src/cdp/session.ts
index 2e0e71f..80fec16 100644
--- a/src/cdp/session.ts
+++ b/src/cdp/session.ts
@@ -43,6 +43,7 @@ export type CdpSession = {
   resolveRef(ref: string): number | undefined;
   /** The active tab's prior ref signatures — baseline for the post-mutation diff. */
   refSignatures(): ReadonlyMap<string, string>;
+  refMappings(): ReadonlyMap<string, number>;
   call<M extends CdpMethod>(method: M, params?: ParamsOf<M>, opts?: { timeoutMs?: number }): Promise<Result<ResultOf<M>, CdpError>>;
   callOnTarget<M extends CdpMethod>(method: M, params: ParamsOf<M>, sessionId: string, opts?: { timeoutMs?: number }): Promise<Result<ResultOf<M>, CdpError>>;
   callBrowser<M extends CdpMethod>(method: M, params?: ParamsOf<M>, opts?: { timeoutMs?: number }): Promise<Result<ResultOf<M>, CdpError>>;
@@ -396,6 +397,10 @@ export const createCdpSession = (
       const tab = targetId ? tabs.get(targetId) : undefined;
       return tab?.refSig ?? new Map();
     },
+    refMappings() {
+      const tab = targetId ? tabs.get(targetId) : undefined;
+      return tab?.refMap ?? new Map();
+    },
     call(method, params, opts) {
       return req(method, params, sessionId, opts);
     },
diff --git a/src/domains/ref-resolve.ts b/src/domains/ref-resolve.ts
index a80c620..822f8e8 100644
--- a/src/domains/ref-resolve.ts
+++ b/src/domains/ref-resolve.ts
@@ -83,14 +83,25 @@ export const interactiveDiff = async (client: BrowserClient): Promise<string> =>
   const targets = collectInteractiveTargets(slim);
 
   // Re-publish fresh refs so later ref calls resolve against the new DOM.
+  const priorRefs = session.refMappings();
+  const refByBackendId = new Map<number, string>();
+  for (const [ref, backendId] of priorRefs) refByBackendId.set(backendId, ref);
+  let nextIndex = 1;
+  for (const ref of priorRefs.keys()) {
+    const digits = /^e(\d+)$/.exec(ref)?.[1];
+    if (digits !== undefined) nextIndex = Math.max(nextIndex, Number(digits) + 1);
+  }
   const refMap = new Map<string, number>();
   const refSig = new Map<string, string>();
-  targets.forEach(({ node, backendId }, i) => {
-    const ref = `e${i + 1}`;
+  const taken = new Set<string>();
+  for (const { node, backendId } of targets) {
+    const prior = refByBackendId.get(backendId);
+    const ref = prior !== undefined && !taken.has(prior) ? prior : `e${nextIndex++}`;
+    taken.add(ref);
     node.ref = ref;
     refMap.set(ref, backendId);
     refSig.set(ref, sigOf(node));
-  });
+  }
   session.setRefMap(refMap, refSig);
 
   // Compare by stable identity (role|name) rather than ref position, since refs
-- 
cgit v1.2.3