Observation Is a Contract, Not a Screenshot
BrowserSkill's observation layer answers the question that follows ownership: what is currently on the page, and which part of that page may the session act on? This chapter explains why semantic observation comes before ordinary interaction, how @eN references stay tied to a tab and document, and when HTML or screenshots provide different kinds of evidence. The practical result is a disciplined loop: read the current page, choose a fresh target, act only within scope, and observe again when the page changes.
A page needs a semantic read before it needs input
A human looking at a page can combine text, layout, labels, focus, and visual context in one glance. An agent calling BrowserSkill needs an explicit read operation that turns some of that context into structured evidence. The simple snapshot path provides an accessibility-oriented view. The richer observe path captures several kinds of page fact—DOM structure, accessibility information, forms, frames, geometry, and, when requested, visual facts—then builds a semantic representation that can be rendered for the agent.
The important point is not that one representation contains every fact. It is that observation gives the agent a current description from which a target can be selected. A button can be understood through its role and name, a field through its label and state, and a nested element through the frame or shadow-root context that contains it. The resulting text is more useful for ordinary control selection than starting with raw HTML or an image and asking the agent to infer all structure from scratch.
BrowserSkill's semantic layer can also expose information that is conditional. Hover discovery is optional because moving the pointer can change the page and has a cost. When enabled, it can reveal a menu surface or a tooltip name that was not present in the initial static capture. That information is still described as a probe result, not silently merged into a timeless page model. The distinction matters: a menu revealed by a hover is evidence about a particular interaction state, and the agent should not assume the surface will remain after the pointer moves or the page updates.
Observation is therefore a read operation with conditions. It targets a session-controlled or otherwise permitted tab, attaches to the relevant document, captures the available facts, and renders them under bounds. If geometry is incomplete, if a frame cannot be verified, or if document identity is uncertain, the observation can include a warning. That warning is part of the evidence. It tells the agent that the page description is usable only with a qualification, rather than inviting it to fill the missing geometry with a guess.
The semantic result is not simply a shortened DOM dump. It combines page structure with accessibility roles, form signals, frame relationships, and the geometry needed to connect a named element to a browser input target. That combination is what lets an agent reason about “the search field” rather than merely search for a string in markup. It also explains why the capture can be incomplete in different ways. A page may provide readable text while a frame's top-level coordinates are unavailable; a control may be present in the accessibility structure while its live document identity cannot be revalidated; a hover surface may appear only after a deliberate probe. Those are different evidence gaps and should lead to different next actions.