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.mdindex 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.goindex 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]RefTargetNodes []A11yNodeDomEpoch 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 backenddiff --git a/internal/bridge/epoch_refs_test.go b/internal/bridge/epoch_refs_test.gonew file mode 100644index 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.gonew file mode 100644index 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.goindex 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 browsetype liteTab struct {window html.Windowurl 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.Navigatl.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) (*browseropsreturn 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.goindex fe42f599..41437138 100644--- a/internal/browsers/ghostchrome/staticfetch/traverse.go+++ b/internal/browsers/ghostchrome/staticfetch/traverse.go@@ -1,7 +1,6 @@package staticfetchimport (- "fmt""strings""github.com/gost-dom/browser/dom"@@ -46,8 +45,7 @@ func (l *Browser) walkDOMInto(acc *[]browserops.SnapshotNode, tab *liteTab, nodereturn}- 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.goindex 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.goindex 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 stringwhy 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.goindex 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.goindex 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.goindex 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]int64var url, title stringvar 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.Refsurl = result.URLtitle = result.Titleif 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"] = truediff --git a/skills/pinchtab-mcp/SKILL.md b/skills/pinchtab-mcp/SKILL.mdindex 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 server3. **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.mdindex 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.)---