RefRegistry class

Static registry mapping [ref=eN] tokens to RefEntry records.

V3 mints a fresh e<N> token every time register is called UNLESS a SemanticsNode is supplied AND a token has already been issued for the same node.id — in which case the previously-issued token is returned and its payload is refreshed in place. This is what makes repeated flutter_snapshot calls on an unchanged tree return identical refs (Step 6 acceptance test (b)).

The dedupe key is node.id ALONE (not groupId + node.id): every snapshot mints a fresh groupId, but the agent should observe stable tokens for stable widgets across snapshots. On a cache hit the entry's stored groupId is updated to the latest snapshot's id so disposal of older snapshot groups never invalidates a token still referenced by a newer snapshot.

Tokens are scoped to a groupId (e.g. snapshot-1700000000000). The owning extension calls disposeGroup when the group is superseded (next snapshot, or page navigation) — every entry whose current groupId matches is removed atomically.

All state is static. Tests must call resetForTesting (or the legacy disposeAll) in setUp to avoid bleed-through between test cases.

Thread safety

All VM Service extension calls arrive on the root isolate. No cross- isolate mutation occurs; no synchronization primitives are needed.

Properties

hashCode → int

The hash code for this object.

no setter, inherited

runtimeType → Type

A representation of the runtime type of the object.

no setter, inherited

Methods

noSuchMethod(Invocation invocation) → dynamic

Invoked when a nonexistent method or property is accessed.

inherited

toString() → String

A string representation of this object.

inherited

Operators

operator ==(Object other) → bool

The equality operator.

inherited

Static Properties

instance → RefRegistry

Sentinel instance for enricher contracts.

final

Static Methods

activeRefs() → Iterable<String>

Returns every currently-registered ref token (both eN and qN).

disposeAll() → void

Removes every entry in the registry and resets the counter.

disposeGroup(String groupId) → void

Removes every entry whose current groupId equals groupId. Subsequent lookup calls for those tokens return null.

lookup(String ref) → RefEntry?

Looks up RefEntry by token. Returns null if the token is unknown or its owning group has been disposed.

lookupQuery(String ref) → DuskQuery?

Looks up the stored DuskQuery for a q<N> token. Returns null when the token is unknown (e.g. after disposeAll, or for e<N> tokens which live in the _entries map instead).

refsForGroup(String groupId) → List<String>

Returns every token whose current groupId equals groupId.

register({required Rect rect, required Element element, required String groupId, required bool isTextField, SemanticsNode? node, RenderObject? renderObject}) → String

Mints (or returns the cached) token for the supplied tree references.

registerForTesting({required Rect rect, required Element element, required String groupId, required bool isTextField}) → String

Registers an entry directly, bypassing the Semantics walk.

registerQuery(DuskQuery query) → String

Mints a fresh q<N> query handle for the supplied predicate set and stores it for subsequent action-tool re-resolution.

resetForTesting() → void

Alias of disposeAll with a clearer name for setUp blocks.