Voice UI Actuators

The problem this solves

Voice integrations are usually built tool by tool: a createInvoice tool, a searchDocuments tool, an openSettings tool. Every one is bespoke, and the assistant's reach is exactly the list someone had time to write. Every new page silently falls outside it, and the user cannot tell which parts of the app listen — the failure is "it didn't do anything," with no error and no explanation.

The alternative is a small vocabulary of universal actions that work against the DOM already on screen. A page nobody voice-enabled is still operable, because "click Save" does not need to know what Save does.

Finding the right element is the whole problem

findClickable() and the input finders carry the accumulated rules, and every one of them exists because a simpler version misfires:

• Exact beats partial. With "Save" and "Save and close" both present, a substring match hits
• whichever comes first in the DOM. That is a coin flip on which button a voice command presses.
• Disabled elements are skipped. Matching one produces a click that silently does nothing —
• from the user's side, indistinguishable from not being heard.
• aria-label is the fallback when there is no visible text. Icon-only buttons are most of a
• toolbar, and a text-only matcher cannot reach any of them.
• Inputs are found four ways — placeholder, aria-label, <label for=id>, and a wrapping
• <label>. Real forms use all four, and supporting only the first two means "type in the email
• box" works on some pages and not others, for reasons invisible to the user.
• nth disambiguates deliberately. When a page genuinely has three "Edit" buttons, the
• caller says which, rather than the library guessing.
• No match returns null. The agent can say "I can't find a Save button here," which is a
• useful sentence. Throwing, or clicking something approximate, is not.

What this does NOT do

No perception. It does not read the screen, take screenshots, or decide what to click — the model and its vision channel do that. This executes a decision already made.

No speech recognition, no intent parsing, no confirmation. Pair it with a confirmation gate before anything destructive; these actuators will happily click Delete.

Client-side only: it needs a real DOM.

Verified

34 tests covering exact-over-partial precedence, case-insensitivity, role filtering, links via role=link and anchors, aria-label fallback, disabled-element skipping, nth disambiguation, all four input-finding strategies, empty input, and the no-match case returning null.

Not covered: no test drives a real browser — jsdom is not Chrome, and shadow DOM, iframes and virtualised lists are untested. Nothing here handles an element that exists but is scrolled out of view or covered by an overlay.