Skip to main content

DOM-Native Execution

DOM-Native Execution is Layer 0 of Hunch's action dispatch system. It works on every website, on day one, with no configuration.

What It Does​

Instead of taking screenshots and simulating clicks with a headless browser, Hunch dispatches real DOM events directly in the page's JavaScript context. This is the same way a human user interacts with a form — typing into inputs, selecting dropdowns, clicking submit — but done programmatically.

How It Works​

Field Discovery​

The executor finds form fields using multiple strategies, tried in order:

  1. name attribute — <input name="email"> or <select name="country">
  2. id attribute — <input id="signup-email">
  3. aria-label attribute — <input aria-label="Email address">
  4. Label text — finds the <label> element associated with the field
  5. Placeholder text — <input placeholder="Enter your email">

Value Setting​

Values are set using native DOM APIs that work with any framework:

  • HTMLInputElement.value = "..." with input and change events dispatched
  • HTMLSelectElement.selectedIndex for dropdown selections
  • React-compatible value setting via Object.getOwnPropertyDescriptor for controlled components

Form Submission​

Forms are submitted using requestSubmit() when a submit button is available, or form.submit() as a fallback. No click simulation on submit buttons.

Why Not Puppeteer​

Previous versions of Hunch used Puppeteer (headless Chrome) for form automation. This approach had several problems:

ProblemPuppeteerDOM-Native
Requires headless browserYesNo
Breaks on SPA navigationCommonNever
Slow (browser startup)~2-5s~0ms
Detectable by anti-botYesNo
Works on mobileNoYes
Framework-agnosticNo (React quirks)Yes

DOM-native execution runs in the visitor's own browser. There is no external browser to launch, no screenshots to parse, no DOM tree to serialize and deserialize. The widget operates in the same JavaScript context as the page itself.

Limitations​

DOM-native execution cannot:

  • Execute JavaScript beyond form events — it cannot trigger custom click handlers outside forms
  • Handle multi-step wizards — each step must complete before the next begins
  • Bypass CAPTCHAs — if a form has a CAPTCHA, the widget stops and asks for manual completion
  • Access cross-origin iframes — forms inside iframes from a different domain cannot be reached

For these cases, the widget falls back to redirecting the visitor to the form's page URL, where they can complete the action manually.

Best Practices​

  1. Use semantic HTML — <label> elements, name attributes, and aria-label help the executor find fields faster
  2. Avoid custom dropdowns — native <select> elements work reliably; custom dropdown components may not
  3. Keep forms simple — single-page forms work best; multi-step wizards need each step to be independently submittable