DOCSEARCHbyAlgolia
Submit Docs

Domscribe

repository·main·Indexed 41 days ago

https://github.com/patchorbit/domscribe

A pixel-to-code development tool that maps running UI elements to their exact source locations. It captures runtime context, including props, state, and DOM snapshots, and provides an MCP (Model Context Protocol) adapter to hand off this data to AI coding agents. Domscribe includes framework-specific adapters for React, Next.js 15+, Nuxt 3+, and Vue, as well as a CLI for managing the relay server.

Tokens
65.9K
Snippets
209
Records
302
Agent score
50%

What's inside Domscribe

  1. What is Domscribe?

    main

    Domscribe is a pixel-to-code development tool designed to bridge the gap between a running web application and its source code. It allows developers to interact with a running app via an in-browser overlay to capture runtime context (like component props, state, and event bindings) and map those interactions directly to exact source locations (file path, line, column, and component name). This context can then be handed off to coding agents (like Claude) via the Model Context Protocol (MCP).

    Key Characteristics:

    • Dev-only: Operates exclusively in development mode. Production builds strip all Domscribe artifacts (data attributes, overlay scripts, relay connections) to ensure zero runtime cost.
    • Stable IDs: Element IDs are designed to survive Hot Module Replacement (HMR) using content-hash caching.
    • Isolated UI: The overlay UI uses Lit web components with Shadow DOM to prevent CSS or JS conflicts with the host application.

  2. Overview of Domscribe packages

    main

    Domscribe is modularized into several packages depending on your integration needs:

    Core & Data

    • @domscribe/core: Zod schemas, RFC 7807 error system, ID generation, PII redaction, and constants.
    • @domscribe/manifest: Append-only JSONL manifest, IDStabilizer (xxhash64), BatchWriter, and ManifestCompactor.
    • @domscribe/relay: Fastify HTTP/WS server, MCP stdio adapter, and annotation lifecycle management.
    • @domscribe/transform: Parser-agnostic AST injection (Acorn, Babel, VueSFC) and bundler plugins.
    • @domscribe/runtime: Browser-side ElementTracker, ContextCapturer, and BridgeDispatch.

    UI & Framework Integrations

    • @domscribe/overlay: Lit web components (shadow DOM), element picker, and annotation UI.
    • @domscribe/react: React fiber walking, props/state extraction, and Vite/Webpack plugins.
    • @domscribe/vue: Vue 3 VNode resolution (Composition + Options API) and Vite/Webpack plugins.
    • @domscribe/next: withDomscribe() config wrapper for Next.js 15 + 16.
    • @domscribe/nuxt: Nuxt 3+ module with auto-relay and runtime plugin.

    CLI & Agent Tools

    • domscribe: CLI binary providing serve, status, stop, init, and mcp commands.
    • @domscribe/mcp: Standalone MCP server binary (domscribe-mcp).
    • @domscribe/test-fixtures: Black-box integration + e2e suite (internal use).

  3. Domscribe Core Features

    main

    Domscribe includes several key technical features for seamless agent integration:

    • Build-time stable IDs: Injects deterministic data-ds attributes via AST that remain stable across HMR (Hot Module Replacement) and fast refresh.
    • Framework & Bundler Support: Supports React (18-19), Vue (3), Next.js (15-16), Nuxt (3+), Vite (5-7), Webpack (5), and Turbopack.
    • Deep Runtime Capture: Inspects React fiber and Vue VNodes to capture live props and state.
    • Zero Production Impact: Instrumentation is automatically stripped in production builds (enforced in CI).
    • PII Redaction: Automatically scrubs sensitive patterns like emails and tokens before data leaves the browser.
    • Annotation Storage: Annotations are stored as JSON files in .domscribe/annotations/ in your repository and exposed via REST APIs for MCP-compatible agents.

  4. What is @domscribe/verify?

    main

    @domscribe/verify is a visual-snapshot comparator designed for Domscribe. It compares two PNG screenshot buffers pixel-by-pixel and returns a structured delta.

    Key characteristics:

    • No DOM/Browser required: It is a pure-TS implementation that does not require a browser environment to run.
    • Environment Agnostic: It can be executed in Node.js CI environments as well as the Domscribe relay runtime.
    • Implementation: It uses pixelmatch for the underlying pixel comparison.

    Note: This is primarily an internal package used by @domscribe/test-fixtures and @domscribe/relay (specifically for the verify_after_edit MCP tool). Most users will interact with it indirectly through these higher-level packages.

  5. Understand the Domscribe Runtime Capture Flow

    main

    When using the overlay's picker mode, Domscribe captures the relationship between the live browser element and the source code. When a user clicks an element:

    1. The ds-picker-overlay captures coordinates.
    2. The OverlayStore identifies the closest ancestor with a [data-ds] attribute.
    3. RuntimeManager.captureForElement(element) is invoked to extract the component instance, serialized props, serialized state, and the component name via a FrameworkAdapter.
    4. The RelayHttpClient resolves the data-ds ID to a ManifestEntry to find the exact source location.
    5. The OverlayStore updates the UI (context panel and element preview) with this metadata.

  6. How Domscribe bridges UI and Code

    main

    Domscribe is a pixel-to-code bridge that maps running UI elements to their exact source locations. It enables two primary workflows:

    1. UI → Code (Annotation Workflow): A user interacts with the browser, creating an 'annotation' (a request to change something). Domscribe captures the element's source location, runtime context (props, state, DOM), and the user's intent. An agent can then claim this annotation and implement the change.
    2. Code → UI (Source Querying): While editing source code, you can query the live browser to see the actual runtime state of a component at a specific file and line number. This reveals the 'live truth' that static code cannot, such as actual applied CSS classes, current props, and component state.

  7. Understand the Annotation Lifecycle

    main

    Annotations follow a specific state machine that facilitates collaboration between developers and AI agents:

    • QUEUED: User creates an annotation via the overlay.
    • PROCESSING: An AI agent picks up the annotation via MCP.
    • PROCESSED: The agent attaches a response and marks it as processed.
    • FAILED: The processing attempt failed.
    • ARCHIVED: The user archives the annotation.

  8. Understand VerifyResult verdicts and semantics

    main

    The domscribe.verify.afterEdit tool returns a VerifyResult containing a verdict. The verdict is determined by comparing computed styles and geometry (bounding rect) against the baseline and any provided expectedChanges.

    SituationVerdictDescription
    No style and no geometry deltano_changeThe element is identical to the baseline.
    No expectations declared, something changedmatchChange was detected, but no specific intent was verified.
    All expectations met, nothing unexpectedmatchThe edit exactly matched the intended changes.
    All expectations met, extra properties changedpartialThe intended changes happened, but unexpected side effects occurred.
    Some expectations met (incl. wrong-value changes)partialThe edit was partially successful or used incorrect values.
    No expectation met, other properties changedregressionThe edit failed to meet expectations and caused other changes.

    Note on Geometry: Geometry (bounding rect) deltas are always reported but do not independently downgrade a verdict, as movement is often a side effect of intended style changes (e.g., increasing padding).

  9. Tab persistence and dragging

    main

    The collapsed tab can be dragged along the right edge of the viewport. To prevent accidental drags when a user intends to click, there is a 4px drag threshold.

    The vertical position of the tab is persisted in localStorage using the key domscribe:tabOffsetY (represented as a value from 0-100%, where 50 is the center).

  10. How Domscribe architecture works

    main

    Domscribe consists of three main layers working together:

    1. Developer's Browser: Contains the Host App (instrumented with data-ds attributes), a Runtime Manager (which uses an Adapter to interface with the framework's VNode/Fiber tree), and the Overlay UI (built with Lit components like ds-tab, ds-sidebar, and ds-picker-overlay).
    2. Relay Server: A Fastify-based server that provides a REST API (/annotations, /manifest, /status), a WebSocket for real-time events, and an MCP Server to provide tools and prompts to coding agents.
    3. Coding Agent: An external agent (e.g., Claude) that consumes the context provided by the Relay Server via the MCP Protocol.

    Communication between the Browser and the Relay Server occurs over HTTP or WebSockets.

    +------------------------------------------------------------------------+
|                        Developer's Browser                             |
|                                                                        |
|  +----------------+   +----------------+   +------------------------+  |
|  | Host App       |   | Runtime        |   | Overlay (Lit)          |  |
|  | (React/Vue)    |<--| Manager        |<--| ds-tab, ds-sidebar,    |  |
|  | + data-ds      |   | + Adapter      |   | ds-picker-overlay      |  |
|  | attributes     |   | (Fiber/VNode)  |   | (Shadow DOM)           |  |
|  +----------------+   +-------+--------+   +-----------+------------+  |
|                                |                        |            |
|                                |    HTTP/WebSocket      |            |
|                                +-----------+------------+              |
+-------------------------------------------|----------------------------+ 
                                            |                             
                                +-----------v------------+                
                                |    Relay Server        |                
                                |    (Fastify)           |                
                                |    Port: dynamic       |                
                                |                        |                
                                |  +------------------+  |                
                                |  | REST API         |  |                
                                |  | /annotations     |  |                
                                |  | /manifest        |  |                
                                |  | /status          |  |                
                                |  +------------------+  |                
                                |  +------------------+  |                
                                |  | WebSocket        |  |                
                                |  | Real-time events |  |                
                                |  +------------------+  |                
                                |  +------------------+  |                
                                |  | MCP Server       |  |                
                                |  | Tools & Prompts  |  |                
                                |  +------------------+  |                
                                +-----------+------------+              
                                            |                             
                                +-----------v------------+                
                                | Coding Agent (Claude)  |                
                                | via MCP Protocol       |                
                                +------------------------+

  11. Understand the Domscribe Build-Time Transform Flow

    main
    Domscribe automates the injection of stable identifiers into your source code during the build process. When a developer saves a file (e.g., .tsx or .vue), the Domscribe plugin intercepts the file, parses the AST, and identifies JSX opening elements. For elements lacking a data-ds attribute, the system generates a stable ID using xxhash64 and position caching, then injects the data-ds="<id>" attribute using magic-string. These mappings are then buffered and flushed to .domscribe/manifest.jsonl to maintain a persistent link between the runtime DOM and the source code.

  12. How the Domscribe build-time pipeline works

    main

    Domscribe uses a build-time pipeline to instrument source code and generate a manifest. The process follows these steps:

    1. Bundler Plugin: A plugin for Vite or Webpack triggers the process.
    2. DomscribeInjector: Performs an AST transformation on the source files.
    3. IDStabilizer: Uses xxhash and caching to ensure element IDs remain stable across builds.
    4. Output Generation: The pipeline produces:
      • Transformed code containing data-ds attributes.
      • Source maps (.map).
      • Manifest entries.
    5. Manifest Persistence: A BatchWriter collects entries (flushing every 50 entries or 100ms) and writes them to a .domscribe/manifest.jsonl file using an append-only JSONL format for crash safety.
    Source File (.tsx/.vue)
        |
        v
+--------------------+     +---------------------+     +--------------------+
| Bundler Plugin     |---->| DomscribeInjector   |---->| IDStabilizer       |
| (Vite/Webpack)     |     | (AST Transform)     |     | (xxhash + cache)   |
+--------------------+     +---------+-----------+     +--------------------+
                                     |                                     
                       +-------------+-------------+                      
                       v             v             v                      
               Transformed     Source Map     ManifestEntries             
               Code + data-ds  (.map)         (-> JSONL file)             
               attributes                                                
                                                                         
                                                                         
                                     +--------------------+              
                                     | BatchWriter        |              
                                     | (50 entries/       |              
                                     |  100ms flush)      |              
                                     +---------+-----------+              
                                               v                          
                                     .domscribe/manifest.jsonl