DocsWorkflowsComponentsMachinemachine:extension:observe

machine:extension:observe

Reads the live page through the connected browser extension and returns its interactive elements as refs a model can name. It is the eye of the authoring loop, and it is useful on its own when a workflow needs to branch on what a page is currently showing.

Options

Name	Type	Description
`url`	`string`	The page to open before observing; empty observes whatever the matched tab already shows
`match_url`	`string`	A substring an open tab's URL must contain for the observation to reuse that tab
`client_id`	`string`	The extension client to observe through, a hint the host may honour; empty leaves the choice of browser to the host
`scope`	`string`	A CSS selector narrowing the observation to one region of the page
`max_nodes`	`int`	How many interactive elements to keep (default 200)
`timeout_ms`	`int`	How long to wait for the browser before failing (default 10 minutes)

Outputs

Name	Type	Description
`observation`	`PageObservation`	The structured snapshot of the page's interactive elements
↳ `url`	`string`	Is the observed page's address.
↳ `title`	`string`	Is the document title.
↳ `nodes`	`[]ObservedNode`	Are the interactive elements, in document order.
↳ `ref`	`string`	Is the short handle for this node ("e1", "e2"), unique inside one observation and meaningless outside it.
↳ `role`	`string`	Is the aria role, explicit or implied by the tag.
↳ `name`	`string`	Is the accessible name, from aria-label, an associated label, the text, the placeholder, the title, or the alt text.
↳ `tag`	`string`	Is the lowercase tag name.
↳ `type`	`string`	Is the input type, for form controls that carry one.
↳ `value`	`string`	Is the current value, capped by the observer and never set for a password input.
↳ `placeholder`	`string`	Is the control's placeholder text.
↳ `disabled`	`bool`	Reports whether the control rejects interaction.
↳ `checked`	`bool`	Is the state of a checkbox or radio.
↳ `expanded`	`bool`	Mirrors aria-expanded.
↳ `options`	`[]string`	Are a select's option values, capped by the observer.
↳ `selector`	`string`	Is the stable CSS selector the observer built for this node, the same one the element picker would produce.
↳ `path`	`string`	Is the structural path, for a node CSS cannot address.
↳ `indexes`	`[]int`	Narrows a multi-match selector to this node's positions.
↳ `enter`	`[]string`	Mirrors Selector.Enter, the shadow hosts and frames to descend through before Selector resolves. Absent for an element in the top document, which is most of them.
↳ `section`	`string`	Names the nearest enclosing landmark or the preceding heading, so a reader can tell two identical controls apart by where they sit.
↳ `context`	`string`	Is the text of the row, card or list item the element sits in, filled in only when the element's own name does not already say which one this is. It is what tells twenty identical add-to-cart buttons apart.
↳ `offscreen`	`bool`	Marks an element laid out outside the current viewport. It is still real and still actionable, since the engine scrolls to it.
↳ `obscured`	`bool`	Marks an element another element covers at its center point, which is what a cookie wall or an open dialog does to the page behind it.
↳ `similar`	`int`	Counts the further siblings left out because they repeat this one's shape. It sits on the last member of a collapsed run.
↳ `headings`	`[]ObservedHeading`	Are the page's headings, in document order.
↳ `level`	`int`	Is the heading level, 1 for h1.
↳ `text`	`string`	Is the heading's text.
↳ `text`	`string`	Is the readable page text, present only when the observation asked for it, capped by the observer.
↳ `truncated`	`bool`	Reports that the node or text cap clipped the page, so a reader knows the snapshot is partial.
↳ `modal`	`string`	Names the dialog or consent wall standing over the page, when one is. Everything outside it is marked obscured, because clicking it is what a browser would refuse to do until the wall is dealt with.
↳ `modal_frame`	`bool`	Says the wall is a cross-origin frame, which is how most consent managers ship. Nothing inside one can be listed or clicked from the page it covers, so getting past it needs another way in rather than a ref from this snapshot.
↳ `omitted`	`int`	Counts the elements the caps and the repeat collapsing left out.
↳ `frames`	`int`	Counts the cross-origin iframes on the page, whose contents no observation can reach from here.
↳ `lists`	`[]ObservedList`	Are the repeated content blocks on the page. Nothing in Nodes describes a review card or a product tile that holds no control, so this is the only thing that says the page has records on it at all.
↳ `ref`	`string`	Is the short handle for this list inside one observation.
↳ `selector`	`string`	Names the item container.
↳ `count`	`int`	Is how many members the selector matched.
↳ `section`	`string`	Names the region of the page the list sits in, when the observer could tell.
↳ `fields`	`[]ObservedListField`	Are the candidate columns, each relative to the item container.
↳ `name`	`string`	Is the column name the observer proposed.
↳ `css`	`string`	Is relative to the item container.
↳ `attribute`	`string`	Names the attribute the column reads, when it reads one.
↳ `sample`	`string`	Is what the column read on the first member, so a caller can tell a price from a rating without opening the page.
↳ `pagination`	`ObservedPagination`	Names the control that reaches the next batch of items, when the page has one.
↳ `kind`	`string`	Is the shape the page uses to reach its next batch, one of link, numbered, more, or infinite.
↳ `selector`	`string`	Targets the control that advances the listing.
↳ `label`	`string`	Is the control's visible text.
↳ `url`	`string`	Is the next page's href when the control is a link.
↳ `pages`	`int`	Counts the numbered page links a pager prints, when it prints any.
`text`	`string`	The same snapshot rendered one line per element, ready to drop into a prompt
`lists`	`[]ObservedList`	The repeated content blocks on the page, each with its item container and candidate columns
↳ `ref`	`string`	Is the short handle for this list inside one observation.
↳ `selector`	`string`	Names the item container.
↳ `count`	`int`	Is how many members the selector matched.
↳ `section`	`string`	Names the region of the page the list sits in, when the observer could tell.
↳ `fields`	`[]ObservedListField`	Are the candidate columns, each relative to the item container.
↳ `name`	`string`	Is the column name the observer proposed.
↳ `css`	`string`	Is relative to the item container.
↳ `attribute`	`string`	Names the attribute the column reads, when it reads one.
↳ `sample`	`string`	Is what the column read on the first member, so a caller can tell a price from a rating without opening the page.
`pagination`	`ObservedPagination`	The control that reaches the next batch of items, absent when the page has none
↳ `kind`	`string`	Is the shape the page uses to reach its next batch, one of link, numbered, more, or infinite.
↳ `selector`	`string`	Targets the control that advances the listing.
↳ `label`	`string`	Is the control's visible text.
↳ `url`	`string`	Is the next page's href when the control is a link.
↳ `pages`	`int`	Counts the numbered page links a pager prints, when it prints any.
`has_next`	`bool`	Whether the page reported a way on to the next batch, which is what a collecting loop branches on
`url`	`string`	Where the page was when it was observed
`wall`	`bool`	Says the page is a sign-in wall standing between the browser and what was asked for, which is a stable answer rather than a page still arriving. Nothing on such a page is a count of anything
`wall_reason`	`string`	Names the signal that decided Wall, empty where there is none
`match_url`	`string`	The substring a later turn finds this tab by, which is the host and path the observation was asked for rather than the one the page landed on. A listing's second page rarely shares its path with its third

Example

name: Read what the page is currently showing
actions:
  - name: page
    component: machine:extension:observe
    vars:
      url: https://example.com/login
      scope: "#login-form"
      max_nodes: 120

outputs:
  elements: "{{ page.text }}"

Edit or read the source on GitHub