Dev.to WebDev 🛠 Dev 👁 0 📖 9 min read

Visible Is a Decision, Not a Property: The Test Operun Runs Before It Will Name a Control

By Chen Yu — building Operun, a local-first browser kernel. Written 2026-11-16. TL;DR Earlier guides in this series covered what a snapshot reads: the three walls that hid text from an a11y snapshot, the 40,0

By Chen Yu — building Operun, a local-first browser kernel. Written 2026-11-16.

TL;DR

Earlier guides in this series covered what a snapshot reads: the three walls that hid text from an a11y snapshot, the 40,000-token budget, and what a @eN handle actually promises. This one is about the gate in front of all of it — the test an element has to pass before the walk is even allowed to give it a line.

getComputedStyle(el).display !== 'none' is the version of that test almost everyone writes first, and it is wrong in both directions at once. It says a control inside a display: none container is visible, because the container's display is what removed it. It says a <div> styled as a card that a page wired a click listener to is invisible, because a <div> has no display value that means "control". And it never asks the question that matters most to an agent: will the thing I am about to act on behave the way the line I just read says it will?

Operun answers visibility with four separate decisions, made in four different places, and the reason they are separate is that they fail differently. An element can be removed by its own styling, removed by an ancestor, removed by an attribute the platform treats as removal, or never have been a control in the first place. Collapsing those into one display check is how a snapshot ends up either naming things that are not on the page, or silently omitting the plain <div> buttons that a generation of web apps is built from.

Visibility is asked of the ancestors, not the element

The test itself is nine lines, and its shape is the point:

function isVisible(node: Element): boolean {
  for (let current: Element | null = node; current !== null; current = current.parentElement) {
    const style = styleOf(current)
    if (style.display === 'none') return false
    if (style.visibility === 'hidden' || style.visibility === 'collapse') return false
  }
  return true
}

It walks the element and every ancestor up to the root. A field inside a display: none panel has its own computed display set to whatever its tag would produce — inline-block for an input — so asking only the element returns true for something the page has taken off the page entirely. The walk costs one computed-style read per level and answers the question the platform actually answers.

Two details are worth more than the loop. First, visibility: collapse is checked alongside hidden, because on table rows it is the value pages actually use and it removes the row just as completely. Second, styleOf resolves the style from the element's own document:

function styleOf(node: Element): CSSStyleDeclaration {
  const view = doc.defaultView ?? window
  return view.getComputedStyle(node)
}

That is not defensiveness. A CSSStyleDeclaration belongs to the document its element lives in, and Chrome raises a TypeError when a window is asked about an element from another document. The ambient window would pass every jsdom test and fail on the first iframe on a real page.

What is deliberately not used is offsetParent or getClientRects. Both are layout products: a real browser has them, a document without layout has neither, and the style engine answers in both. A visibility test that only works when the page happens to have been laid out is a test that fails on exactly the frames that need it most.

The same walk decides the tab order, and that is not a coincidence — it is ADR-020 D-11. A control the snapshot reports but Tab skips, or one Tab reaches but no line mentions, is a disagreement between two answers the agent is entitled to treat as one page.

Three other routes a page uses to remove a control

The style walk covers one route. A page has others, and each one needs its own check because none of them shows up in a computed style:

if (node.closest('[hidden], [aria-hidden="true"], [inert]') !== null) continue

[hidden] is the attribute route: it computes to display: none only if the page's stylesheet has not overridden it, which is legal and common. aria-hidden="true" is the accessibility route: the element is on screen and out of the tree, and for an a11y snapshot that is the whole question. [inert] is the interaction route, and it is the one an agent feels most: the subtree is rendered, readable, and completely unreachable by any pointer or focus operation.

Note closest() rather than matches(). All three are inherited in effect — aria-hidden on a modal's backdrop does not need repeating on every child, and inert never needs repeating at all. Asking the element alone would report every child of an inert dialog as a live control.

Two exclusions sit next to that check and are, deliberately, not visibility tests at all:

if (node.tagName === 'OPTION') continue
if (node.tagName === 'INPUT' && node.type === 'hidden') continue

An <option> inside a native <select> is often laid out and would pass the style walk, but no action this kernel has can pick one — the DOM gives no way to click it, and the parent already reports the chosen value. A ref there would be a handle to nothing. A custom listbox built from [role="option"] elements is reported, because those a click can reach. Same visual result on screen, opposite decision, and the difference is capability rather than appearance.

input[type=hidden] is excluded by what it is rather than by how it is styled. It normally computes to display: none and would fall to the visibility test anyway — but a page is free to lay one out, and it is still not a control. Filtering it in the visibility function would have been the wrong home for that rule.

Disabledness is asked of the selector

The last gate is the one where a wrong answer is worst, because the agent reads a line, decides, acts, and the action silently disagrees with the reading.

Every guard that refused a disabled control used to read the disabled IDL property. That property reflects only the element's own attribute, so a control disabled by an ancestor fieldset reads as enabled:

<fieldset disabled><input id="locked" /></fieldset>
<script>
  document.getElementById('locked').disabled            // false — the trap
  document.getElementById('locked').matches(':disabled') // true  — the guard
</script>

A type into that field passed the guard, wrote into a field the page had taken out of service, and reported SUCCESS. The tab order had the mirror-image defect: the control stayed in the order, so a Tab landed somewhere the platform would have skipped.

All four guards — click, type, tabbability, and press's text-edit path — now ask node.matches(':disabled'), the selector the style engine already resolves, which is the one place fieldset inheritance is implemented for free. It is also safe on a non-form element: :disabled matches nothing rather than throwing, so no tag test is needed in front of it. And the snapshot line says the same thing the primitive will do:

if (node.matches(':disabled')) line += ', disabled'

That line is why a disabled control appears in the snapshot with the flag rather than disappearing. Hiding it would be a worse lie than showing it — the agent needs to know the button exists and is not available, otherwise "there is no submit button" and "the submit button is locked" become the same observation, and only one of them is true.

The roleless div, and the guard against noise

None of the above helps a page whose buttons are plain <div>s with a delegated click listener, which is a large fraction of the modern web. The DOM offers no way to enumerate listeners, so the kernel falls back to four signals: a cursor: pointer, an onclick attribute, a tabindex that is not -1, or contenteditable.

The weakest of the four needs its own guard, because it is inherited by everything inside a clickable row:

if (pointer && !declared) {
  const parent = node.parentElement
  if (parent !== null && styleOf(parent).cursor === 'pointer') return undefined
  return ', cursor=pointer'
}

Without that check, every <span> and <svg> inside a clickable card becomes a control, and a snapshot of a product listing becomes unreadable — a page of twenty items produces hundreds of lines, all of them technically true and none of them useful. When the hint survives, it is written into the line as cursor=pointer, because it is evidence rather than a fact: pages style hover states too, and an agent deciding whether to act deserves to know which of the four signals produced the handle.

Visible is not the same as in view

One distinction is worth stating plainly, because it is a common source of surprise: this test does not ask whether the element is inside the viewport. A button three thousand pixels below the fold passes isVisible, gets a line, and is a perfectly good target. That is correct — the page has not removed it, and an agent working through a long form should not have to scroll before it can even see what exists.

Bringing it into view is the action layer's job, and it does so with scrollIntoView({ behavior: 'instant', block: 'center' }) before the click. Center rather than nearest, because a control scrolled to the very edge of the viewport is a control whose hit box may be half outside it.

That split has a failure mode worth naming: a scroll that silently does not happen leaves the page exactly where it was, so every later step still "works", on the wrong part of the page. It is the one primitive whose failure is easiest to miss precisely because nothing breaks.

What this buys, and where it stops

The cost of a walk that is correct is a walk that is complete: every element in the document is visited and classified, whether or not it ends up on a line. That is why the 40,000-token budget matters and why it is applied at the end, on the finished list, with a trailer that says what was dropped:

… 137 more elements omitted

A truncated snapshot that does not say it was truncated is indistinguishable from a complete one, and an agent that believes it has seen the whole page stops looking.

What is not reproduced is worth reading as a limit rather than a bug. Chrome's role resolution for platform widgets — <video controls>, a native date picker, <summary> — is approximated by a table or not reported at all. Chrome's name computation consults widget internals that no DOM walk can reach, so a control whose name the platform synthesises will read as unnamed here. And the walk is a walk: an element a framework has not yet mounted cannot be classified, which is why the honest instruction is to snapshot after the page settles rather than as soon as it loads.

Conclusion

The reason to write these four gates down separately is that they are four different questions, and every one of them has a plausible-looking shortcut that answers a different question. Ancestors, not the element. Attributes the platform treats as removal, not just styling. The selector, not the property. Capability, not appearance. Each shortcut passes its own happy-path test and fails on the first real page — which is exactly the shape of failure an agent cannot diagnose from the outside, because the trace says SUCCESS.

A local-first browser kernel gets judged on this harder than a hosted service does, because there is no server-side log to reconcile afterwards: the snapshot, the action, and the report all come from the same document, and if the three disagree the agent has no second opinion to consult. That is why the visibility decision lives in one function, why the tab order shares it, and why the line the agent reads is generated by the same selector the click will honour.

About Operun

Operun is a local-first browser kernel: a browser automation runtime that drives a real Chrome through a control plane you run yourself, with an a11y snapshot, a token budget you set, and no page data leaving the machine.

If you are building agents that have to act on pages rather than describe them, the parts worth stealing are the boring ones — an ancestors-first visibility test, a :disabled selector instead of an IDL property, and a truncation trailer that admits what it dropped.

📰 Read the original article on Dev.to WebDev

Originally published by Dev.to WebDev. Aggregated on AIWithGhost for educational purposes — full credit and traffic to the original publisher.