Skip to main content
Versioned element refs are GSD Browser’s core mechanism for reliable, deterministic browser interaction. Rather than asking you to write CSS selectors or XPath expressions that silently break when the DOM changes, GSD Browser scans the live page, assigns each interactive element a stable ref, and version-stamps the entire set. Any interaction command that uses a ref from an older snapshot version is automatically rejected — you always know when you are working with fresh data.

​
How a snapshot works

Run gsd-browser snapshot on any loaded page. The daemon traverses the live DOM, identifies interactive and semantically meaningful elements, and assigns each one a ref in the format @vN:eM — where N is the snapshot version number and M is the element index within that snapshot. 
gsd-browser snapshot
Example output on https://example.com: 
@v1:e1  [a]       "More information..." (href="/more")
After you navigate or the page changes, take a new snapshot: 
gsd-browser navigate https://example.com/search
gsd-browser snapshot
The version counter increments — every ref from this snapshot starts with @v2:: 
@v2:e1  [input]   type="search" placeholder="Find docs..."
@v2:e2  [button]  "Search"
@v2:e3  [a]       "Advanced search"
Passing @v1:e1 to a command after taking snapshot v2 raises a stale-ref error immediately, before any interaction reaches Chrome. This fail-fast behaviour prevents the subtle wrong-element bugs that plague selector-based automation.
Always take a fresh snapshot after navigation, form submission, dialog interactions, or any other action that changes the page structure. Old refs do not automatically refresh — they become stale and will be rejected.

​
Snapshot modes

The default snapshot captures interactive elements only. Pass --mode to focus on a specific semantic category:
ModeWhat it captures
interactive (default)Buttons, links, inputs, selects, and other actionable elements
formAll form fields, labels, and submit controls
dialogElements inside open dialogs and modals
navigationNav links, breadcrumbs, and pagination controls
errorsVisible error messages, validation feedback, and alerts
headingsPage headings (h1–h6) for structural orientation
visible_onlyEvery visible element, not limited to interactive ones
# Capture only form fields on a checkout page
gsd-browser snapshot --mode form

# Capture everything visible for a full-page audit
gsd-browser snapshot --mode visible_only
You can also scope a snapshot to a part of the page with --selector: 
gsd-browser snapshot --selector "#main-content"

​
Interacting with refs

All interaction commands accept either a ref or a CSS selector. Use refs whenever you have a current snapshot — they are more robust than selectors because the daemon validates the version stamp before acting. 
gsd-browser click @v2:e2
# or by selector
gsd-browser click "button[type='submit']"

​
Inspecting a specific ref

gsd-browser get-ref returns full metadata for any ref — bounding box, ARIA role and name, element tag, structural signature, and the resolved CSS selector the daemon uses internally: 
gsd-browser get-ref @v2:e1

{
  "ref": "@v2:e1",
  "tag": "input",
  "type": "search",
  "aria_role": "searchbox",
  "aria_label": "Find docs...",
  "placeholder": "Find docs...",
  "bounding_box": { "x": 120, "y": 80, "width": 400, "height": 40 },
  "selector": "#search-input"
}
This is particularly useful when debugging why an interaction failed or when you want to understand the structural context of an element.

​
Best practices for AI agents

1

Always snapshot before interacting

Read the gsd-browser://latest-snapshot MCP resource (or call browser_snapshot) after every navigation and after any action that changes the DOM. This gives your agent fresh, versioned refs before it attempts any interaction.
2

Prefer semantic tools first

Use browser_act or browser_find_best for common intents (fill email, click submit, accept cookies, etc.) before dropping down to ref-based interaction. Semantic tools use the action cache automatically and are more resilient to minor DOM changes.
3

Fall back to refs for precision

When browser_act doesn’t cover your case, or when you need to click a very specific element, take a snapshot and use the resulting refs. Refs give you exact, version-validated targeting.
4

Re-snapshot after state changes

After clicking a button that triggers a navigation or a form submission that refreshes the page, always re-snapshot before your next interaction. The snapshot version will increment and give you fresh, valid refs for the new page state.

​
The action cache and self-healing

Every time an agent successfully maps an intent (like fill_email) to a concrete selector on a given page, GSD Browser can store that mapping in the action cache. On future visits to the same page, the cache is consulted first — if the mapping is still valid, the interaction proceeds immediately without another round-trip to find the element. 
# Inspect action cache statistics
gsd-browser action-cache stats

# View cached mappings for the current session
gsd-browser action-cache get

# Clear the cache if you want to start fresh
gsd-browser action-cache clear
The cache is scoped per session. A --session checkout cache never contaminates a --session dashboard cache. Over long-running agent projects, the cache makes interactions progressively faster and more robust — the system effectively learns the page’s element structure from prior successes.
Use named sessions with a consistent name per project. The action cache accumulates knowledge across every run on that session, giving you compounding reliability gains over time.