5,000 to 10,000 tokens. That's what my AI agent was burning before changing a single line of frontend code. I started paying attention to this a while back. I'd ask the agent to do something small ("fix the padding on that card," "swap this to the secondary variant") and the actual edit would be maybe 200 tokens of real work. But the agent wouldn't start with the edit. It would start with a search. Grepping the codebase, reading five files, asking me "is this the right component?", reading more files, building more context. All of that before it touched a line of code. And the thing that kept bugging me wasn't the token cost itself; it was what the token cost was doing to my iteration speed. I work in fast loops. Change something, see the result, change something else. That's how frontend development is supposed to feel. But when every small UI tweak comes with a 30-second search phase and thousands of tokens of overhead, those fast loops turn into slow, expensive ones. The worst part is that I KNEW which element I was looking at. I just had no way to point my agent at it and say "this one, right here, go." Instead, every interaction started from zero; the agent rebuilding context it shouldn't have needed to rebuild. That's the problem Domscribe solves. Not by making the agent smarter at searching, but by eliminating the search entirely. Domscribe The gap is a topology problem Okay, let me back up for a second and explain why this problem is harder than it sounds. (I promise this isn't a HUGE tangent; it matters for understanding the design.) Your source code and your rendered DOM are two completely different topologies. You might have a Button component defined in components/ui/Button.tsx, but when it renders, it's wrapped in three HOCs, passed through a context provider, conditionally rendered inside a layout component, and the actual <button> element in the DOM is like five abstractions deep from where you'd naturally go looking. Button components/ui/Button.tsx <button> An AI agent that reads your source files has zero visibility into this. It can see your file tree. It can read your code. But it cannot see what's actually rendering in the browser, or map a DOM element back to the line of code that created it. Every frontend edit starts with a search problem, and the search is blind. This is what Domscribe fixes. What if the DOM already knew? What if every DOM element just... already knew where it came from? Not via runtime heuristics. Not via CSS selectors that break when you rename a class. Not via _debugSource which is a React-only workaround that doesn't survive production-like builds. What if we did it at build time, deterministically, and made the mapping permanent? _debugSource That's the core of Domscribe. At build time, an AST transform walks your JSX and Vue templates, assigns every element a deterministic ID, and writes a manifest that maps each ID to its exact file, line, and column. At runtime, framework adapters capture live props and state from the component tree. A local relay daemon connects the browser and your agent via MCP. How the build-time injection actually works I want to get into the weeds here because I think the implementation is genuinely interesting (and also because I'm proud of it and this is my article so I get to be self-indulgent). The transform layer hooks into your bundler's transform phase via Vite, Webpack, or Turbopack. For each source file, it parses the AST, finds every JSX element or Vue template element, and injects a data-ds attribute with an 8-character ID. data-ds The ID generation uses xxhash64, which is stupidly fast (sub-millisecond for typical component files). The algorithm works like this: compute the xxhash64 of the entire file content, then derive a deterministic ID from hash(fileHash + lineNumber:columnNumber) and map it to a base58 alphabet. Same file content, same element position, same ID. Every time. hash(fileHash + lineNumber:columnNumber) Why does this matter? HMR. During hot module replacement, you're constantly re-transforming files. If the IDs changed on every rebuild, you'd lose the mapping between what's in the browser and what's in the manifest. So I built an IDStabilizer with a per-file content hash and a position-keyed cache. If the file content hasn't changed, it returns the existing ID from cache; I'm targeting greater than 80% cache hit rate during HMR, and so far it's holding up in practice. IDStabilizer The manifest itself is append-only JSONL. A BatchWriter buffers entries in memory and flushes in batches of 50, with a 100ms auto-flush interval and a process exit handler so nothing gets lost. Each entry carries a fileHash, so when a file is modified, the reader knows which entries are stale (different hash) and which are current. A compactor periodically cleans up stale entries when the count exceeds a threshold. BatchWriter fileHash (I should mention that the atomic write pattern here is temp file then rename. I've been burned by corrupt JSON files before and I will NOT be burned again.) The part I'm most proud of: the architecture Okay, here's where I need to talk about something that I genuinely care about, even though it's the kind of thing that usually makes people's eyes glaze over. The extensibility of this system. When I started building Domscribe, I could've just written a Babel transform for JSX, a React fiber walker, a Vite plugin, and called it a day. It would've worked. For React. With Vite. And nothing else. But that's the kind of decision that comes back to haunt you at 2 AM when someone opens an issue saying "does this work with Vue?" and the answer is "well, technically, if you rewrite everything..." So I designed the whole thing around two adapter interfaces. On the transform side, there's a ParserInterface. It defines the contract for parsing source files and finding elements: parse(), findJSXOpeningElements(), getInsertPosition(), hasDataDsAttribute(), getLocation(), getTagName(). That's it. The DomscribeInjector takes any ParserInterface implementation and handles all the ID generation, attribute injection, source map chaining, and manifest writing without knowing or caring which parser produced the AST. ParserInterface parse() findJSXOpeningElements() getInsertPosition() hasDataDsAttribute() getLocation() getTagName() DomscribeInjector ParserInterface I built three implementations: AcornParser for plain JSX (used by Vite, where esbuild has already stripped TypeScript), BabelParser for TSX (used by Webpack and Turbopack), and VueSFCParser for Vue single-file components. They're registered in an InjectorRegistry that maps file extensions to parser-injector pairs and manages lifecycle as a unit. AcornParser BabelParser VueSFCParser InjectorRegistry On the runtime side, there's a FrameworkAdapter interface: getComponentInstance(), captureProps(), captureState(). The React adapter walks the fiber tree; it finds fibers via the internal __reactFiber$ keys on DOM elements, walks up to the nearest component fiber, and extracts props from memoizedProps and hook state by traversing the memoizedState linked list. It supports three capture strategies: DevTools hook (most reliable), direct fiber access (fastest), and best-effort (tries both). The Vue adapter does the equivalent via VNode inspection, handling both Composition API and Options API, with ref unwrapping so you get actual values instead of reactive proxies. FrameworkAdapter getComponentInstance() captureProps() captureState() __reactFiber$ memoizedProps memoizedState Here's the thing I want to emphasize: the React and Vue adapters are built on the SAME public interfaces that any community contributor would use. There are no internal escape hatches. No private APIs that the first-party adapters get access to and third-party ones don't. If someone wants to build a Svelte adapter or a Lit adapter or a Solid adapter, they implement ParserInterface for the template syntax and FrameworkAdapter for runtime capture, and the entire downstream pipeline (element tracking, PII redaction, the relay, MCP tools, the overlay) just works. ParserInterface FrameworkAdapter I put probably too many hours into getting this right. But it's the kind of investment that turns a tool into a platform, and I genuinely believe that distinction matters. Two workflows that didn't exist before So what does all of this actually give you in practice? Two things. Code to UI. Your agent is editing Button.tsx line 12. It calls domscribe.query.bySource with the file path and line number, and instantly gets back the live DOM snapshot, current props, component state, and rendered attributes. No screenshots. No human in the loop. The agent can verify what an element looks like BEFORE changing it and confirm the result AFTER. This is the "give your agent eyes on the frontend" workflow. Code to UI. Button.tsx domscribe.query.bySource UI to Code. You click an element in the browser overlay, type "make this button use the primary color" in the annotation input, and submit. Domscribe captures the element's source location, runtime context, and your intent as an annotation. Your agent picks it up via MCP (atomically; no two agents can claim the same annotation), navigates to the exact file and line, implements the change, and sends a response back via WebSocket that shows up in the overlay in real time. UI to Code. The overlay itself is built as Lit web components inside shadow DOM, specifically so it can't interfere with your app's styles or DOM. (I learned this lesson the hard way. During early development, the overlay's CSS was leaking into host apps in ways that were, let's say, not subtle. Shadow DOM fixed that entirely.) The stuff you'd ask about in code review A few things I want to get ahead of because I know this audience will ask. PII. All captured data passes through a redaction layer before it leaves the browser. It pattern-matches against emails, phone numbers, credit cards, SSNs, API keys, JWTs, and IPs, plus it scrubs known sensitive field names recursively. This is ON by default. I didn't want privacy to be a "remember to configure it" thing. PII. Production safety. Everything is stripped in production builds. Zero data-ds attributes, zero overlay scripts, zero relay connections. The Next.js wrapper and Nuxt module only activate in dev mode, and @domscribe/overlay is aliased to a no-op stub in production as a safety net. Production safety. data-ds @domscribe/overlay Testing. The entire integration and e2e suite runs against real published packages via a local Verdaccio registry. No mocked package resolution. The CI pipeline publishes all packages to a local registry, installs them into 14 standalone fixture apps (React 18/19, Vue 3, Next.js 15/16, Nuxt 3, across Vite, Webpack, and Turbopack), and runs Playwright e2e tests that pierce shadow DOM. If the overlay breaks in a real Next.js 16 Turbopack app, CI catches it. Testing. Network isolation. The relay server binds to localhost only. WebSocket connections are local only. MCP uses stdio transport. Nothing is exposed to the network. This is a dev tool, not a SaaS product, and the architecture reflects that. Network isolation. Agent support I built first-party plugins for Claude Code, GitHub Copilot CLI, Gemini CLI, and Cursor. Each one bundles the MCP config and a skill file that teaches the agent how to use Domscribe's tools effectively; install the plugin and you're running in seconds, no manual MCP configuration needed. But the MCP layer means any compatible agent works out of the box. Domscribe exposes 12 tools and 4 prompts. The tools cover source querying, manifest resolution, annotation lifecycle (create, claim, respond, search), and system status. The prompts guide agents through common workflows like processing the next annotation or exploring a component's metadata. (I'll shamelessly admit that I'm hoping people build integrations for agents I haven't gotten to yet. The interface is clean and the MCP surface is well-documented. Wink wink.) The setup experience I put real effort into making the onboarding not suck. There's a setup wizard (npx domscribe init) that handles framework detection, bundler configuration, and agent plugin installation interactively. But if you want manual control, the setup is two steps: add the bundler plugin to your app config, add the MCP config to your agent. npx domscribe init For Next.js it looks like this: import { withDomscribe } from '@domscribe/next';
export default withDomscribe()(nextConfig); import { withDomscribe } from '@domscribe/next';
export default withDomscribe()(nextConfig); For Nuxt: export default defineNuxtConfig({
  modules: ['@domscribe/nuxt'],
}); export default defineNuxtConfig({
  modules: ['@domscribe/nuxt'],
}); That's it. Start your dev server and the relay auto-starts, the overlay appears, and your agent can connect. What I still don't know I want to be honest about the open questions, because pretending I have all the answers would be dishonest and also boring. I don't know how well this scales to truly massive codebases. The manifest is append-only JSONL with hash-based staleness detection, and the batch writer is optimized for throughput, but I haven't tested it against a monorepo with 10,000 components. My gut says it'll be fine (the IDStabilizer cache and the two-pass read algorithm should handle it) but "my gut says" is not a benchmark. IDStabilizer I also don't know what the adapter story looks like for frameworks I haven't built for yet. The ParserInterface and FrameworkAdapter interfaces are clean, but I designed them based on JSX, Vue templates, React fibers, and Vue VNodes. Will they need changes when someone tries to build a Svelte adapter? Maybe. Probably not for the parser side (Svelte's template syntax compiles to DOM operations in a way that should map cleanly to the existing injection model). The runtime side might need more thought — Svelte's reactivity model is quite different from React's fiber tree or Vue's VNode hierarchy. ParserInterface FrameworkAdapter These are the kinds of unknowns that I think are best resolved by people actually trying it, not by me speculating in an article. Which is my not-at-all-subtle way of saying: contributions are very welcome. What Domscribe is really about If I zoom all the way out, here's what I think this project represents. AI coding agents are getting really good at reading and writing code. That part of the problem is largely solved. What's NOT solved is giving those agents spatial awareness of the applications they're building. An agent can read your source files, but it can't see your running frontend. It can edit a component, but it can't verify what that component looks like in the browser. Domscribe is infrastructure for closing that gap. Not by adding another layer of AI on top (please, we have enough of those), but by solving it at the fundamental layer — deterministic build-time source mapping with runtime context capture, exposed through a standard protocol that any tool can consume. I built it as a tool. But I designed it as a platform. And I genuinely believe the distinction will matter as the AI-assisted development ecosystem matures. MIT licensed. Fully open source. The whole codebase is on GitHub at github.com/patchorbit/domscribe, and the docs are at domscribe.com. github.com/patchorbit/domscribe domscribe.com I'd love to hear what you think.

Domscribe Gives AI Agents Eyes on Your Frontend

About Author

Comments

TOPICS

THIS ARTICLE WAS FEATURED IN

Related Stories

Use Claude in Cursor Without Paying API Token Fees

“Generative Engine Optimization is not a Trend” , ICODA CEO Vlad Pivnev on the AI Search Shift

TinyBrain++: A Compact, Interpretable Alternative to Black-Box AI

The Noonification: Use This 7-Step McKinsey Framework to Solve Any Problem (1/10/2023)

The Noonification: A Taxonomy of Inclusiveness (1/11/2024)

The Noonification: What is the InfiniteNature-Zero AI Model? (11/19/2022)

Use Claude in Cursor Without Paying API Token Fees

“Generative Engine Optimization is not a Trend” , ICODA CEO Vlad Pivnev on the AI Search Shift

TinyBrain++: A Compact, Interpretable Alternative to Black-Box AI

The Noonification: Use This 7-Step McKinsey Framework to Solve Any Problem (1/10/2023)

The Noonification: A Taxonomy of Inclusiveness (1/11/2024)

The Noonification: What is the InfiniteNature-Zero AI Model? (11/19/2022)

Light-Mode

Classic

Newspaper

Minty

Dark-Mode

Neon Noir

Minty

HN StartUps