feat(browser): mark snapshot elements that appeared since the previous snapshot

After an action the agent saw a fresh snapshot but no hint of what changed, so
a popup, suggestion list, or validation message looked like any other line.
The page now remembers which elements an earlier snapshot of the document
listed, and later snapshots mark the rest new (the first snapshot marks
nothing).

Author: waleedlatif1

apps/desktop/src/main/browser-agent/page-functions.test.ts

@@ -115,6 +115,7 @@ beforeEach(() => {
   for (const state of window.__simAgentMutationStates ?? []) state.observer.disconnect()
   window.__simAgentMutationStates = undefined
   window.__simAgentNextElementId = 0
+  window.__simAgentShownElements = undefined
   window.__simAgentResolveElement = undefined
   installDomShims()
   Reflect.deleteProperty(document, 'activeElement')
@@ -748,6 +749,23 @@ describe('collectSnapshot', () => {
     expect(outline).not.toContain('button "x" [ref=999]')
   })
 
+  it('marks elements that appeared since the previous snapshot as new', () => {
+    document.body.innerHTML = '<button>Compose</button>'
+    visible(document.querySelector('button') as HTMLButtonElement)
+    expect(outlineOf(collectSnapshot())).not.toContain(' new')
+
+    const dialog = document.createElement('div')
+    dialog.innerHTML = '<input aria-label="Recipients"><button>Send</button>'
+    document.body.append(dialog)
+    dialog.querySelectorAll('*').forEach((el) => visible(el as HTMLElement))
+    const lines = outlineOf(collectSnapshot()).split('\n')
+
+    expect(lines.find((line) => line.includes('"Compose"'))).not.toMatch(/ new$/)
+    expect(lines.find((line) => line.includes('"Recipients"'))).toMatch(/ new$/)
+    expect(lines.find((line) => line.includes('"Send"'))).toMatch(/ new$/)
+    expect(outlineOf(collectSnapshot())).not.toContain(' new')
+  })
+
   it('sanitizes a malicious role so it cannot forge a second snapshot line', () => {
     document.body.innerHTML = '<div tabindex="0" aria-label="Safe control"></div>'
     const control = visible(document.querySelector('div') as HTMLDivElement)

apps/desktop/src/main/browser-agent/page-functions.ts

@@ -41,6 +41,8 @@ declare global {
       observedRoots: WeakSet<ParentNode>
     }>
     __simAgentNextElementId?: number
+    /** Elements an earlier snapshot of this document listed; a later snapshot marks the rest `new`. */
+    __simAgentShownElements?: WeakSet<Element>
     /** Why the last __simAgentResolveElement call returned null — read by the
      * shared stale-error producers so a refusal names its cause instead of
      * the blanket "the page changed". Cleared on every successful resolve. */
@@ -160,6 +162,11 @@ export function collectSnapshot(startingElementId = 0, elementId?: number): unkn
     context: string
   }> = []
   window.__simAgentElements = registry
+  const previouslyShown = window.__simAgentShownElements
+  const shown = previouslyShown ?? new WeakSet<Element>()
+  window.__simAgentShownElements = shown
+  /** Whether an element appeared since the previous snapshot; the first snapshot marks nothing. */
+  const isNew = (el: Element): boolean => previouslyShown !== undefined && !shown.has(el)
   const lines: string[] = []
   let truncated = false
   let refCount = 0
@@ -553,6 +560,8 @@ export function collectSnapshot(startingElementId = 0, elementId?: number): unkn
         parts.push(`${attribute}=${value}`)
       }
     }
+    if (isNew(el)) parts.push('new')
+    shown.add(el)
     const suffix = parts.length > 0 ? ` ${parts.join(' ')}` : ''
     const lineIndex = lines.length
     if (push(`${indent}- ${role} ${quote(name)} [ref=${id}]${suffix}`)) {
@@ -574,8 +583,10 @@ export function collectSnapshot(startingElementId = 0, elementId?: number): unkn
     if (!text) return
     const id = registerElement(el, roleFor(el), text)
     textLineCount++
+    const marker = isNew(el) ? ' new' : ''
+    shown.add(el)
     const lineIndex = lines.length
-    if (push(`${indent}- text ${quote(text)} [ref=${id}]`)) refLineIndexes[id] = lineIndex
+    if (push(`${indent}- text ${quote(text)} [ref=${id}]${marker}`)) refLineIndexes[id] = lineIndex
   }
 
   const headingLevel = (el: Element): number | null => {