agent-source-dom

Dev-only React JSX runtime shim for code-aware browser agents.

It stamps JSX call-site source into the DOM as data-test-src="file:line" so an agent can target UI by source file instead of exploring the whole page.

Why this is useful

Browser agents are often slow and expensive because they have to infer which DOM node belongs to which piece of code.

This package makes that mapping explicit in development.

Instead of repeatedly reading the page and guessing at selectors, an agent can do this:

document.querySelectorAll('[data-test-src*="step-workspace.tsx"]');

That makes browser interactions cheaper, faster, and more deterministic.

How it works

In React dev mode, the JSX transform passes source metadata into jsxDEV(...).

This package wraps react/jsx-dev-runtime and adds a data-test-src attribute during element creation:

data-test-src="src/features/onboarding/step-workspace.tsx:362"

The production runtime stays a pass-through to react/jsx-runtime, so production bundles do not pay for this behavior.

Install

npm install agent-source-dom

Setup

In your app tsconfig.json:

{
  "compilerOptions": {
    "jsx": "react-jsx",
    "jsxImportSource": "agent-source-dom"
  }
}

If you are using Next.js and consuming this from a workspace package, add it to transpilePackages:

module.exports = {
  transpilePackages: ["agent-source-dom"],
};

Example queries

Find interactive elements rendered by a file:

const INTERACTIVE =
  "button, a, input, select, textarea, [role='button'], [role='link'], [role='menuitem'], [role='tab'], [role='checkbox']";

[...document.querySelectorAll('[data-test-src*="step-workspace.tsx"]')].filter(
  (el) => el.matches(INTERACTIVE),
);

Click the Continue button from a specific file:

[...document.querySelectorAll('[data-test-src*="step-workspace.tsx"]')]
  .filter((el) => el.matches("button, a, [role='button']"))
  .find((el) => /continue/i.test(el.textContent || ""))
  ?.click();

Target a single exact JSX line:

document.querySelector(
  '[data-test-src="src/features/onboarding/step-workspace.tsx:362"]',
);

What this is

• a tiny primitive for code-aware browser automation
• useful for MCP browser tools and agent-driven QA loops
• easiest to pair with a prompt that tells the agent to prefer source-scoped selectors

What this is not

• not a full testing framework
• not a replacement for Playwright or Cypress
• not useful for production analytics

Prompting note

The package is most effective when paired with a workflow like:

1. read the source file that owns the interaction
2. query the browser with data-test-src
3. click or fill based on source-scoped selectors
4. wait for the expected outcome in the same browser round-trip

That is where most of the cost and reliability gains show up.