Skip to content

High-performance browser automation bridge and multi-instance orchestrator with advanced stealth injection and real-time dashboard.

feat: make a snapshot ref denote a DOM node rather than a row index, so refs survive a change of filter, selector or depth (PIN-090)

Luigi Agosti8d22f58c969b
diff --git a/README.md b/README.md
index b38ab5ed..624ce60a 100644
--- a/README.md
+++ b/README.md
@@ -174,7 +174,7 @@ Most users should not need to think about `pinchtab bridge` directly, and only n
- **Headless or Headed** — Run without a window or with visible Chrome
- **Multi-instance** — Run multiple parallel Chrome processes with isolated profiles
- **Self-contained** — ~15MB binary, no external dependencies
-- **Accessibility-first** — Stable element refs instead of fragile coordinates
+- **Accessibility-first** — Element refs that denote a DOM node, not a row: the same `e5` survives a change of filter, selector or depth (filtered views are sparse), and expires only on navigation to a new document
- **ARM64-optimized** — First-class Raspberry Pi support with automatic Chromium detection
- **CloakBrowser support** — Optional drop-in provider for sites that fingerprint stock Chromium. PinchTab launches a user-supplied CloakBrowser binary; no CloakBrowser is bundled in released artifacts. See [docs/guides/cloakbrowser.md](docs/guides/cloakbrowser.md).
diff --git a/internal/bridge/bridge_types.go b/internal/bridge/bridge_types.go
index 5b410867..ad757736 100644
--- a/internal/bridge/bridge_types.go
+++ b/internal/bridge/bridge_types.go
@@ -4,6 +4,7 @@ import (
"context"
"fmt"
"net"
+ "strconv"
"time"
"github.com/pinchtab/pinchtab/internal/browserops"
@@ -43,6 +44,150 @@ type RefCache struct {
Targets map[string]RefTarget
Nodes []A11yNode
DomEpoch string
+ Book *RefBook
+}
+
+// RefBook gives each backend DOM node a stable ref within a DOM epoch: a node
+// keeps the ref it was first assigned, and an unseen node gets the next number.
+// This is what makes a ref denote a node rather than a row index, so the same
+// node keeps its ref across a change of filter, depth, selector, token budget or
+// republish. Refs are therefore sparse in a filtered view. A node with a zero
+// backend id carries no identity: alongside resolvable nodes it gets a fresh ref
+// every read and is never resolvable, so its instability is harmless; a snapshot
+// made entirely of such nodes is a statically fetched page whose refs are kept
+// stable per element by the static browser itself and are preserved untouched.
+type RefBook struct {
+ byNode map[int64]string
+ next int
+}
+
+func NewRefBook() *RefBook {
+ return &RefBook{byNode: make(map[int64]string)}
+}
+
+func (b *RefBook) assign(backendNodeID int64) string {
+ if backendNodeID != 0 {
+ if ref, ok := b.byNode[backendNodeID]; ok {
+ return ref
+ }
+ }
+ ref := fmt.Sprintf("e%d", b.next)
+ b.next++
+ if backendNodeID != 0 {
+ b.byNode[backendNodeID] = ref
+ }
+ return ref
+}
+
+// Rebind stamps each node with its stable ref and returns the ref→backend-node
+// map for the resolvable nodes. A snapshot carrying no resolvable node is a
+// statically fetched page: the static browser already keeps each ref stable per
+// element, so its refs are left untouched — renumbering them against this book's
+// counter would put them out of step with the static browser's own ref→element
+// map and resolve a later action to the wrong element.
+func (b *RefBook) Rebind(nodes []A11yNode) map[string]int64 {
+ if !anyResolvable(nodes) {
+ return map[string]int64{}
+ }
+ refs := make(map[string]int64, len(nodes))
+ for i := range nodes {
+ ref := b.assign(nodes[i].NodeID)
+ nodes[i].Ref = ref
+ if nodes[i].NodeID != 0 {
+ refs[ref] = nodes[i].NodeID
+ }
+ }
+ return refs
+}
+
+func anyResolvable(nodes []A11yNode) bool {
+ for i := range nodes {
+ if nodes[i].NodeID != 0 {
+ return true
+ }
+ }
+ return false
+}
+
+func (b *RefBook) sharesNode(nodes []A11yNode) bool {
+ for i := range nodes {
+ if nodes[i].NodeID == 0 {
+ continue
+ }
+ if _, ok := b.byNode[nodes[i].NodeID]; ok {
+ return true
+ }
+ }
+ return false
+}
+
+// bookFromCache returns a fresh copy of the epoch's ref book, so each publish
+// grows its own copy rather than mutating one shared across concurrent reads. A
+// cache published before the book existed — the ghost-chrome escalation seam
+// carries only Refs — is seeded from those refs, so the refs already handed out
+// survive the transition to Chrome.
+func (c *RefCache) bookFromCache() *RefBook {
+ book := NewRefBook()
+ if c == nil {
+ return book
+ }
+ if c.Book != nil {
+ for id, ref := range c.Book.byNode {
+ book.byNode[id] = ref
+ }
+ book.next = c.Book.next
+ return book
+ }
+ for ref, id := range c.Refs {
+ if id == 0 {
+ continue
+ }
+ book.byNode[id] = ref
+ if n, ok := refNumber(ref); ok && n >= book.next {
+ book.next = n + 1
+ }
+ }
+ return book
+}
+
+func refNumber(ref string) (int, bool) {
+ if len(ref) < 2 || ref[0] != 'e' {
+ return 0, false
+ }
+ n, err := strconv.Atoi(ref[1:])
+ if err != nil {
+ return 0, false
+ }
+ return n, true
+}
+
+// EpochRefs rebinds nodes against the tab's DOM-epoch ref book and returns the
+// RefCache to publish. When the nodes share a backend node with the prior epoch
+// it carries that epoch's book and vocab token, so a node keeps its ref across
+// filter, depth, selector and republish reads and the superseded-vocabulary
+// guard does not fire. When they share none — a fresh document — it starts a new
+// epoch: a book numbering from e0 and a fresh vocab token.
+func EpochRefs(prev *RefCache, nodes []A11yNode) *RefCache {
+ book := prev.bookFromCache()
+ vocab := ""
+ if prev != nil {
+ vocab = prev.DomEpoch
+ }
+ if !book.sharesNode(nodes) {
+ book = NewRefBook()
+ vocab = ""
+ }
+ if vocab == "" {
+ vocab = MintVocabToken()
+ }
+ refs := book.Rebind(nodes)
+ return &RefCache{
+ Refs: refs,
+ Targets: RefTargetsFromNodes(nodes),
+ Nodes: nodes,
+ DomEpoch: vocab,
+ Book: book,
+ }
}
// Lookup answers whether a ref names a node that can be acted on. A zero backend
diff --git a/internal/bridge/epoch_refs_test.go b/internal/bridge/epoch_refs_test.go
new file mode 100644
index 00000000..0ebf96b6
--- /dev/null
+++ b/internal/bridge/epoch_refs_test.go
@@ -0,0 +1,132 @@
+package bridge
+
+import "testing"
+
+func refOf(nodes []A11yNode, nodeID int64) string {
+ for i := range nodes {
+ if nodes[i].NodeID == nodeID {
+ return nodes[i].Ref
+ }
+ }
+ return ""
+}
+
+// The core guarantee: a ref denotes a node, not a row. The same node keeps its
+// ref across a filtered, scoped or depth-limited re-read, and a filtered view is
+// therefore SPARSE — it returns the surviving nodes' original refs (e1, e3), not
+// a fresh dense run (e0, e1). The vocabulary token is carried, so the superseded
+// guard stays silent for the reader that changed only its filter.
+func TestARefSurvivesAChangeOfFilterAndTheFilteredViewIsSparse(t *testing.T) {
+ full := []A11yNode{{NodeID: 10}, {NodeID: 20}, {NodeID: 30}, {NodeID: 40}}
+ c1 := EpochRefs(nil, full)
+
+ want := map[int64]string{10: "e0", 20: "e1", 30: "e2", 40: "e3"}
+ for id, ref := range want {
+ if got := refOf(full, id); got != ref {
+ t.Fatalf("first read: node %d ref = %q, want %q", id, got, ref)
+ }
+ }
+
+ // A filtered / scoped re-read that keeps only two of the four nodes, in a
+ // different slice, must return their ORIGINAL refs.
+ filtered := []A11yNode{{NodeID: 40}, {NodeID: 20}}
+ c2 := EpochRefs(c1, filtered)
+ if got := refOf(filtered, 20); got != "e1" {
+ t.Errorf("node 20 ref after filter = %q, want e1 — a ref must denote the node, not its row", got)
+ }
+ if got := refOf(filtered, 40); got != "e3" {
+ t.Errorf("node 40 ref after filter = %q, want e3", got)
+ }
+ if _, dense := c2.Refs["e0"]; dense {
+ t.Errorf("filtered view is dense (e0 present); it must be sparse: %v", c2.Refs)
+ }
+ if c2.DomEpoch != c1.DomEpoch {
+ t.Errorf("vocabulary token changed on a filter-only re-read (%q -> %q); the superseded guard would fire spuriously", c1.DomEpoch, c2.DomEpoch)
+ }
+}
+
+// A genuinely new document — no backend node id shared with the prior read —
+// starts a fresh epoch: refs renumber from e0 and a new vocabulary token is
+// minted, so an action carrying a stale ref+token is refused loudly rather than
+// resolved against the wrong node.
+func TestANewDocumentStartsAFreshEpochAndSupersedesTheToken(t *testing.T) {
+ c1 := EpochRefs(nil, []A11yNode{{NodeID: 10}, {NodeID: 20}})
+ newDoc := []A11yNode{{NodeID: 99}, {NodeID: 88}}
+ c2 := EpochRefs(c1, newDoc)
+
+ if c2.DomEpoch == c1.DomEpoch {
+ t.Error("a new document kept the prior vocabulary token; the superseded guard could not fire")
+ }
+ if got := refOf(newDoc, 99); got != "e0" {
+ t.Errorf("new epoch first node ref = %q, want e0", got)
+ }
+}
+
+// A statically fetched page carries no backend identity: every node has id zero
+// and its ref is minted by the static browser, which keeps it stable per element.
+// EpochRefs must PRESERVE those refs — renumbering them positionally would put
+// the published ref out of step with the static browser's own ref->element map
+// and resolve a later click to the wrong element.
+func TestStaticRefsArePreservedNotRenumbered(t *testing.T) {
+ // A sparse, out-of-order static ref set, exactly as a filtered static re-read
+ // produces it.
+ static := []A11yNode{{Ref: "e5", NodeID: 0}, {Ref: "e2", NodeID: 0}}
+ c := EpochRefs(nil, static)
+
+ if static[0].Ref != "e5" || static[1].Ref != "e2" {
+ t.Fatalf("static refs were renumbered to %q,%q; they must be preserved verbatim", static[0].Ref, static[1].Ref)
+ }
+ if len(c.Refs) != 0 {
+ t.Errorf("zero-id static nodes were made resolvable via the handler cache: %v", c.Refs)
+ }
+ if _, ok := c.Lookup("e5"); ok {
+ t.Error("a zero-id static ref resolved through the handler cache; it must resolve through the static browser only")
+ }
+
+ // A second static read (different subset) still leaves the refs alone.
+ static2 := []A11yNode{{Ref: "e2", NodeID: 0}}
+ EpochRefs(c, static2)
+ if static2[0].Ref != "e2" {
+ t.Errorf("static ref renumbered on a re-read to %q, want e2", static2[0].Ref)
+ }
+}
+
+// The ghost-chrome escalation seam publishes a cache with only Refs (static ref
+// string -> Chrome backend node id) and no Book. The next Chrome read must seed
+// its book from those Refs so the node the agent already holds as e3 keeps e3
+// after escalation, rather than being renumbered — the instability this whole
+// change exists to remove, reintroduced at the seam.
+func TestEscalationSeamPreservesTheStaticRefString(t *testing.T) {
+ escalation := &RefCache{Refs: map[string]int64{"e3": 100}}
+ chromeNodes := []A11yNode{{NodeID: 100}, {NodeID: 200}}
+ c := EpochRefs(escalation, chromeNodes)
+
+ if got := refOf(chromeNodes, 100); got != "e3" {
+ t.Errorf("node 100 ref after escalation = %q, want e3 — the static ref must survive the transition to Chrome", got)
+ }
+ if c.Refs["e3"] != 100 {
+ t.Errorf("ref e3 no longer resolves to node 100 after escalation: %v", c.Refs)
+ }
+ if got := refOf(chromeNodes, 200); got == "e3" {
+ t.Error("a newly seen node collided with the carried static ref e3")
+ }
+}
+
+// A zero-id node mixed in among resolvable nodes has no identity to key on, so it
+// gets a fresh positional ref every read and is never resolvable. That instability
+// is harmless precisely because such a ref never enters the resolvable set.
+func TestAZeroIdNodeAmongResolvableNodesIsNeverResolvable(t *testing.T) {
+ mixed := []A11yNode{{NodeID: 10}, {NodeID: 0}, {NodeID: 20}}
+ c := EpochRefs(nil, mixed)
+
+ zeroRef := mixed[1].Ref
+ if zeroRef == "" {
+ t.Fatal("the zero-id node was not stamped with a ref")
+ }
+ if _, ok := c.Refs[zeroRef]; ok {
+ t.Errorf("the zero-id node's ref %q is resolvable; a node with no backend id must never resolve", zeroRef)
+ }
+ if c.Refs["e0"] != 10 || c.Refs["e2"] != 20 {
+ t.Errorf("resolvable nodes lost their refs among a zero-id node: %v", c.Refs)
+ }
+}
diff --git a/internal/bridge/observe/snapshot_format_sparse_test.go b/internal/bridge/observe/snapshot_format_sparse_test.go
new file mode 100644
index 00000000..40783204
--- /dev/null
+++ b/internal/bridge/observe/snapshot_format_sparse_test.go
@@ -0,0 +1,35 @@
+package observe
+
+import (
+ "strings"
+ "testing"
+)
+
+// A filtered view hands the formatter a sparse ref set — e0, e1, e6 — because a
+// ref now denotes a node rather than a row. The formatter writes each node's own
+// ref verbatim; it must never renumber to a dense e0, e1, e2 run, or the printed
+// ref would no longer match the ref the agent must echo back to act on the node.
+func TestFormattersPreserveASparseRefSet(t *testing.T) {
+ nodes := []A11yNode{
+ {Ref: "e0", Role: "button", Name: "Alpha"},
+ {Ref: "e1", Role: "link", Name: "Beta"},
+ {Ref: "e6", Role: "textbox", Name: "Gamma"},
+ }
+
+ for _, tc := range []struct {
+ name string
+ out string
+ want string // the sparse ref that must survive
+ dense string // the dense ref that must NOT appear
+ }{
+ {"text", FormatSnapshotText(nodes), "e6 textbox", "e2 "},
+ {"compact", FormatSnapshotCompact(nodes), "e6:textbox", "e2:"},
+ } {
+ if !strings.Contains(tc.out, tc.want) {
+ t.Errorf("%s formatter dropped the sparse ref e6:\n%s", tc.name, tc.out)
+ }
+ if strings.Contains(tc.out, tc.dense) {
+ t.Errorf("%s formatter renumbered the sparse set to dense (found %q):\n%s", tc.name, tc.dense, tc.out)
+ }
+ }
+}
diff --git a/internal/browsers/ghostchrome/staticfetch/staticfetch.go b/internal/browsers/ghostchrome/staticfetch/staticfetch.go
index 8f72fe16..81f0b2d0 100644
--- a/internal/browsers/ghostchrome/staticfetch/staticfetch.go
+++ b/internal/browsers/ghostchrome/staticfetch/staticfetch.go
@@ -24,7 +24,26 @@ var ErrStaticNotSupported = errors.New("operation not supported by static browse
type liteTab struct {
window html.Window
url string
- refMap map[string]dom.Element
+ // refMap resolves a ref back to its element and refByEl gives an element its
+ // stable ref. Both persist for the tab's life and grow across snapshots so a
+ // ref denotes an element rather than a row index: the same element keeps its
+ // ref across a change of filter, and refs are sparse in a filtered view. The
+ // static DOM never mutates, so entries never go stale; a new page is a new
+ // tab with fresh maps.
+ refMap map[string]dom.Element
+ refByEl map[dom.Element]string
+ refNext int
+}
+
+func (t *liteTab) assignRef(el dom.Element) string {
+ if ref, ok := t.refByEl[el]; ok {
+ return ref
+ }
+ ref := fmt.Sprintf("e%d", t.refNext)
+ t.refNext++
+ t.refByEl[el] = ref
+ t.refMap[ref] = el
+ return ref
}
type Browser struct {
@@ -96,9 +115,10 @@ func (l *Browser) Navigate(ctx context.Context, url string) (*browserops.Navigat
l.seq++
tabID := fmt.Sprintf("lite-%d", l.seq)
l.tabs[tabID] = &liteTab{
- window: win,
- url: url,
- refMap: make(map[string]dom.Element),
+ window: win,
+ url: url,
+ refMap: make(map[string]dom.Element),
+ refByEl: make(map[dom.Element]string),
}
l.current = tabID
@@ -130,7 +150,6 @@ func (l *Browser) Snapshot(_ context.Context, tabID, filter string) (*browserops
return nil, errors.New("no body element")
}
- tab.refMap = make(map[string]dom.Element)
nodes := l.walkDOM(tab, body, filter, 0)
title := l.getTitle(tab.window)
diff --git a/internal/browsers/ghostchrome/staticfetch/traverse.go b/internal/browsers/ghostchrome/staticfetch/traverse.go
index fe42f599..41437138 100644
--- a/internal/browsers/ghostchrome/staticfetch/traverse.go
+++ b/internal/browsers/ghostchrome/staticfetch/traverse.go
@@ -1,7 +1,6 @@
package staticfetch
import (
- "fmt"
"strings"
"github.com/gost-dom/browser/dom"
@@ -46,8 +45,7 @@ func (l *Browser) walkDOMInto(acc *[]browserops.SnapshotNode, tab *liteTab, node
return
}
- ref := fmt.Sprintf("e%d", len(tab.refMap))
- tab.refMap[ref] = el
+ ref := tab.assignRef(el)
sn := browserops.SnapshotNode{
Ref: ref,
diff --git a/internal/handlers/action_execution.go b/internal/handlers/action_execution.go
index 51db2c68..8408823b 100644
--- a/internal/handlers/action_execution.go
+++ b/internal/handlers/action_execution.go
@@ -454,14 +454,9 @@ func (h *Handlers) refreshRefCache(ctx context.Context, tabID string) {
if err != nil {
return
}
- flat, refs := bridge.BuildSnapshot(nodes, bridge.FilterInteractive, -1)
+ flat, _ := bridge.BuildSnapshot(nodes, bridge.FilterInteractive, -1)
_ = bridge.EnrichA11yNodesWithDOMMetadata(ctx, flat)
- h.Bridge.SetRefCache(tabID, &bridge.RefCache{
- Refs: refs,
- Targets: bridge.RefTargetsFromNodes(flat),
- Nodes: flat,
- DomEpoch: bridge.MintVocabToken(),
- })
+ h.Bridge.SetRefCache(tabID, bridge.EpochRefs(h.Bridge.GetRefCache(tabID), flat))
}
func isTimeoutWithPendingDialog(err error, tabID string, b bridge.BridgeAPI) bool {
diff --git a/internal/handlers/action_vocab_test.go b/internal/handlers/action_vocab_test.go
index 9d87f2a3..4f107d33 100644
--- a/internal/handlers/action_vocab_test.go
+++ b/internal/handlers/action_vocab_test.go
@@ -149,9 +149,11 @@ func TestTheGETFormCarriesAndEnforcesTheToken(t *testing.T) {
}
}
-// Every publish mints a fresh token, so any renumbering publish supersedes the previous one —
-// this is why a same-options republish (the stale-ref retry re-runs the interactive filter)
-// still supersedes, which a hash-of-options token would not.
+// A new epoch mints a fresh token, so a publish that renumbers a tab's refs (a new document)
+// supersedes the previous one. A same-document republish does NOT mint a fresh token — EpochRefs
+// carries the prior epoch's token — which is what stops the annotate and stale-ref-retry paths
+// from superseding a ref the agent still holds. This test only pins that the mint, when it does
+// happen, yields a distinct non-empty token.
func TestEachMintedTokenIsDistinctAndNonEmpty(t *testing.T) {
seen := map[string]bool{}
for i := 0; i < 64; i++ {
@@ -166,24 +168,27 @@ func TestEachMintedTokenIsDistinctAndNonEmpty(t *testing.T) {
}
}
-// Wiring census: the guard above only refuses when the tab's cached token differs from the
-// request's, so it is inert unless every ref-publishing site actually MINTS and stores a fresh
-// token. This is the browserless proof of criteria one and four — that /snapshot publishes a
-// token and that the annotate and stale-ref-retry paths supersede — since those handlers reach
-// live CDP and cannot be driven by the package mock. Dropping the mint at any site reddens here
-// while leaving the behavioural gate tests green, so this census is load-bearing.
-func TestEveryRefPublishSiteMintsAVocabularyToken(t *testing.T) {
+// Wiring census: the epoch ref book is what makes a ref denote a node across reads, and it also
+// owns the vocabulary token — carrying it across a same-document republish and minting a fresh one
+// only for a new document. Every ref-publishing site must route through bridge.EpochRefs, or that
+// site reverts to a bare cache: a hand-rolled cache would either mint a fresh token on every
+// republish (superseding refs the agent still holds — the exact regression criteria three and five
+// forbid) or renumber refs positionally. This is the browserless proof for those criteria, since
+// the handlers reach live CDP and cannot be driven by the package mock. Dropping the EpochRefs call
+// at any site reddens here while leaving the behavioural gate tests green, so this census is
+// load-bearing.
+func TestEveryRefPublishSiteRoutesThroughTheEpochRefBook(t *testing.T) {
for _, tc := range []struct {
file string
- want string
why string
}{
- {"snapshot.go", "MintVocabToken", "the /snapshot response is the primary vocabulary a client reads and echoes"},
- {"screenshot_annotate.go", "MintVocabToken", "the annotate path republishes with a hardcoded interactive filter and must supersede"},
- {"action_execution.go", "MintVocabToken", "the stale-ref retry refreshes the cache and must supersede a ref minted before it"},
+ {"snapshot.go", "the /snapshot response is the primary vocabulary a client reads and echoes"},
+ {"capture.go", "the /capture response publishes the same tab vocabulary as /snapshot"},
+ {"screenshot_annotate.go", "the annotate path republishes with a hardcoded interactive filter and must not supersede an existing ref"},
+ {"action_execution.go", "the stale-ref retry refreshes the cache and must not supersede a ref minted before it"},
} {
- if !fileCallsSelector(t, tc.file, tc.want) {
- t.Errorf("%s does not call bridge.%s, so this publish site stores no token and the guard is inert for it — %s", tc.file, tc.want, tc.why)
+ if !fileCallsSelector(t, tc.file, "EpochRefs") {
+ t.Errorf("%s does not call bridge.EpochRefs, so this publish site does not route through the epoch ref book — %s", tc.file, tc.why)
}
}
diff --git a/internal/handlers/capture.go b/internal/handlers/capture.go
index 2a969c69..11e45b07 100644
--- a/internal/handlers/capture.go
+++ b/internal/handlers/capture.go
@@ -172,13 +172,9 @@ func (h *Handlers) HandleCapture(w http.ResponseWriter, r *http.Request) {
return
}
- h.Bridge.SetRefCache(resolvedTabID, &bridge.RefCache{
- Refs: result.Refs,
- Targets: bridge.RefTargetsFromNodes(result.Nodes),
- Nodes: result.Nodes,
- DomEpoch: result.DomEpoch,
- })
- w.Header().Set(vocabHeader, result.DomEpoch)
+ cache := bridge.EpochRefs(h.Bridge.GetRefCache(resolvedTabID), result.Nodes)
+ h.Bridge.SetRefCache(resolvedTabID, cache)
+ w.Header().Set(vocabHeader, cache.DomEpoch)
imageInfo := map[string]any{
"format": result.ImageFormat,
@@ -231,7 +227,7 @@ func (h *Handlers) HandleCapture(w http.ResponseWriter, r *http.Request) {
"epoch": map[string]any{
"frameId": result.FrameID,
"loaderId": result.LoaderID,
- "domEpoch": result.DomEpoch,
+ "domEpoch": cache.DomEpoch,
},
"pairing": map[string]any{
"navigated": result.Navigated,
diff --git a/internal/handlers/screenshot_annotate.go b/internal/handlers/screenshot_annotate.go
index 224d2104..e675b8b9 100644
--- a/internal/handlers/screenshot_annotate.go
+++ b/internal/handlers/screenshot_annotate.go
@@ -54,19 +54,14 @@ func (h *Handlers) collectScreenshotAnnotations(
target = rect
}
- flat, refs := bridge.BuildSnapshot(rawNodes, "interactive", -1)
+ flat, _ := bridge.BuildSnapshot(rawNodes, "interactive", -1)
if len(flat) == 0 && selector == "" {
// Pages with no AX-interactive content (canvas-heavy fixtures, etc.)
// fall back to the unfiltered tree so the agent still gets a layout.
- flat, refs = bridge.BuildSnapshot(rawNodes, "", -1)
+ flat, _ = bridge.BuildSnapshot(rawNodes, "", -1)
}
- h.Bridge.SetRefCache(tabID, &bridge.RefCache{
- Refs: refs,
- Targets: bridge.RefTargetsFromNodes(flat),
- Nodes: flat,
- DomEpoch: bridge.MintVocabToken(),
- })
+ h.Bridge.SetRefCache(tabID, bridge.EpochRefs(h.Bridge.GetRefCache(tabID), flat))
items = make([]cdptk.AnnotationItem, 0, len(flat))
for _, n := range flat {
diff --git a/internal/handlers/snapshot.go b/internal/handlers/snapshot.go
index db8d4f25..73d31757 100644
--- a/internal/handlers/snapshot.go
+++ b/internal/handlers/snapshot.go
@@ -108,7 +108,6 @@ func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {
}
var flat []bridge.A11yNode
- var refs map[string]int64
var url, title string
var scopeNodeID int64
@@ -156,7 +155,7 @@ func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {
return
}
- flat, refs = bridge.BuildSnapshot(rawNodes, filter, maxDepth)
+ flat, _ = bridge.BuildSnapshot(rawNodes, filter, maxDepth)
_ = bridge.EnrichA11yNodesWithDOMMetadata(tCtx, flat)
url, _ = h.Bridge.CurrentURL(tCtx)
title, _ = h.Bridge.CurrentTitle(tCtx)
@@ -170,7 +169,6 @@ func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {
return
}
flat = result.Nodes
- refs = result.Refs
url = result.URL
title = result.Title
if result.Route != nil {
@@ -213,21 +211,15 @@ func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {
flat, truncated = bridge.TruncateToTokens(flat, maxTokens, format)
}
+ prev := h.Bridge.GetRefCache(resolvedTabID)
var prevNodes []bridge.A11yNode
- if doDiff {
- if prev := h.Bridge.GetRefCache(resolvedTabID); prev != nil {
- prevNodes = prev.Nodes
- }
+ if doDiff && prev != nil {
+ prevNodes = prev.Nodes
}
- vocab := bridge.MintVocabToken()
- h.Bridge.SetRefCache(resolvedTabID, &bridge.RefCache{
- Refs: refs,
- Targets: bridge.RefTargetsFromNodes(flat),
- Nodes: flat,
- DomEpoch: vocab,
- })
- w.Header().Set(vocabHeader, vocab)
+ cache := bridge.EpochRefs(prev, flat)
+ h.Bridge.SetRefCache(resolvedTabID, cache)
+ w.Header().Set(vocabHeader, cache.DomEpoch)
h.recordResolvedURL(r, url)
@@ -452,7 +444,7 @@ func (h *Handlers) HandleSnapshot(w http.ResponseWriter, r *http.Request) {
"route": snapChromeRoute,
"nodes": flat,
"count": len(flat),
- "vocabularyToken": vocab,
+ "vocabularyToken": cache.DomEpoch,
})
if truncated {
resp["truncated"] = true
diff --git a/skills/pinchtab-mcp/SKILL.md b/skills/pinchtab-mcp/SKILL.md
index d371618d..5bd1d622 100644
--- a/skills/pinchtab-mcp/SKILL.md
+++ b/skills/pinchtab-mcp/SKILL.md
@@ -21,7 +21,7 @@ Use MCP tools to control a browser through the PinchTab HTTP API. The MCP server
3. **Interact**: `pinchtab_click(selector="e5")` — use refs from the snapshot.
4. **Verify**: `pinchtab_get_text()` or re-snapshot to confirm the action succeeded.
-**Critical rule**: Element refs (`e5`, `e12`) are ephemeral. They expire after navigation or DOM updates. Always re-call `pinchtab_snapshot` after a page load before using refs. Refs are also renumbered — with no navigation and no DOM change — by any snapshot taken with different options (`interactive` vs full, a `selector`, a `depth` limit), so never use a ref from one snapshot after a differently-optioned one; take the ref from the most recent snapshot. The tools carry each snapshot's vocabulary token forward automatically, so a ref from a superseded snapshot is refused with `vocab_superseded` rather than acting on the wrong element.
+**Critical rule**: An element ref (`e5`, `e12`) denotes a DOM node, so the same node keeps its ref across `interactive` vs full, a `selector` scope and a `depth` limit — a filtered view is therefore sparse (`e0, e1, e6`), never assume refs are contiguous. What a ref does NOT survive is navigation to a new document: refs expire on page load, so always re-call `pinchtab_snapshot` afterwards. A ref that can no longer resolve to its node is refused with `vocab_superseded` (or `ref not found`), never acted on positionally — the tools carry each snapshot's vocabulary token forward so a filter-only re-read keeps a ref valid while a new document supersedes it.
---
@@ -344,7 +344,7 @@ For these, use the pinchtab CLI or HTTP API directly.
## Element Ref Best Practices
-1. **Never cache refs across navigations or across differently-optioned snapshots.** Always re-snapshot after `pinchtab_navigate` or `pinchtab_click(waitNav=true)`, and never carry a ref from a full snapshot into an `interactive`/`selector`/`depth` one — the numbering differs. The tools track each snapshot's vocabulary token, so a stale ref surfaces as a `vocab_superseded` refusal instead of a wrong-element click.
+1. **Re-snapshot after navigation; a ref survives a change of filter, selector or depth.** Always re-snapshot after `pinchtab_navigate` or `pinchtab_click(waitNav=true)` — a new document expires every ref. But within one page a ref denotes a node, so carrying `e5` from a full snapshot into an `interactive`/`selector`/`depth` read is safe and returns the same node (filtered views are sparse — `e0, e1, e6`). The tools track each snapshot's vocabulary token, so a truly stale ref surfaces as a `vocab_superseded` refusal instead of a wrong-element click.
2. **Use `diff=true` after interactions.** Shows only changed elements, saving tokens.
3. **Prefer refs over CSS selectors.** Refs resolve by backend node IDs, more reliable than CSS.
4. **Refs work across iframes.** Same-origin iframe content is flattened into the main tree — refs are clickable without frame hops.
diff --git a/skills/pinchtab/references/mcp.md b/skills/pinchtab/references/mcp.md
index 580475a7..9c83bd9c 100644
--- a/skills/pinchtab/references/mcp.md
+++ b/skills/pinchtab/references/mcp.md
@@ -123,9 +123,11 @@ All tool names are prefixed with `pinchtab_`.
`pinchtab_snapshot` returns an accessibility tree with element refs like `e5`, `e12`. These refs can be passed as the `selector` value on interaction tools, and legacy `ref` is still accepted on the element-action tools.
-**Important:** Refs are ephemeral. They expire after navigation or significant DOM updates. Always re-call `pinchtab_snapshot` after a page load before using refs in interactions.
+**A ref denotes a DOM node, not a row.** Within one page the same node keeps the same ref across every read of it — a full snapshot, an `interactive` filter, a `selector` scope, a `depth` limit, a different token budget, an annotated screenshot, or an internal stale-ref recovery all return the same `e5` for the same element. This means a **filtered view is sparse**: dropping the non-interactive nodes returns `e0, e1, e6`, not a fresh `e0, e1, e2` run. Do not assume refs are contiguous or that the highest ref equals the node count.
-A ref is numbered by its position in one snapshot response, so it can also be superseded **without any navigation or DOM change**: a snapshot taken with different options (`interactive`, a `selector`, a `depth` limit), an annotated screenshot, an internal stale-ref recovery, or another client sharing the tab all renumber the refs — the same `e1` then denotes a different live element. The MCP tools guard this for you: `pinchtab_snapshot` records the response's vocabulary token per tab and the interaction tools send it back on the next action, so a ref minted under a snapshot that a later differently-optioned snapshot has renumbered is refused with `409` `vocab_superseded` and re-snapshot advice, rather than silently clicking the wrong node. (The token travels as the `X-PinchTab-Vocab` response header, also `vocabularyToken` in the JSON snapshot body, and a `vocab` request field. It is optional on the wire — a raw HTTP caller that does not echo it keeps the previous behaviour and stays exposed to the silent rebind until it opts in.)
+**What still invalidates a ref:** navigation to a new document. When the page navigates, the old refs are gone and the tab starts a fresh ref vocabulary — always re-call `pinchtab_snapshot` after a page load before using refs. A ref that can no longer be resolved to the node it named still fails loudly (`vocab_superseded` or `ref not found`) and is never resolved positionally against whatever snapshot ran last.
+
+The MCP tools carry a per-tab vocabulary token so the guard fires only on a real supersession: a snapshot that merely changes filter, selector or depth keeps the token, so a ref you already hold stays valid; a snapshot of a new document mints a new token, so a stale ref+token is refused with `409` `vocab_superseded` and re-snapshot advice rather than clicking the wrong node. (The token travels as the `X-PinchTab-Vocab` response header, also `vocabularyToken` in the JSON snapshot body, and a `vocab` request field. It is optional on the wire — a raw HTTP caller that does not echo it keeps the previous behaviour until it opts in.)
---